1503501 - (webext-tb-docs) Documentation for WebExtension APIs

Status: RESOLVED FIXED

(Thunderbird :: Add-Ons: Extensions API, enhancement)

Description

[Geoff Lankow (:darktrojan)]

We need somewhere and somehow to document our new APIs in human-friendly form. I've created a Python script to read the API schemas and create reStructuredText (rst) files from them, which I'm then (manually) pushing to a GitHub repo and publishing at https://thunderbird-webextensions.readthedocs.io/en/latest/

It's all just a test at the moment, but we'll need to think about automating the process: we should be able get TaskCluster to publish for us when it notices changes. Do we keep the documents in the tree, and if so, how do we make sure they get updated when they should?

Comment 1

[Magnus Melin [:mkmelin]]

I think Firefox has this automated already(?)

Comment 2

[Geoff Lankow (:darktrojan)]

It does. I don't think they'll be too happy if I start putting our docs in with theirs though.

Comment 3

[Magnus Melin [:mkmelin]]

Sure, but the code for it should be available somewhere, and we can set another publishing url.

Comment 4

[ExE Boss]

Attachment: MDN: Add Thunderbird to the browser compatibility data

Many of the WebExtension APIs implemented by Firefox are also implemented by Thunderbird, so I’d prefer to keep documentation of both on MDN.

Comment 5

[Florian Scholz (Open Web Docs)]

Please this this answer: https://github.com/mdn/browser-compat-data/pull/2333#issuecomment-435333658

Comment 6

[Philipp Kewisch [:Fallen] [:📆][:🧩]]

While there are common APIs, they might have a different meaning that would be hard to integrate into MDN without making it confusing. For example, the tabs API doesn't allow you to access all the tabs.

I think RTD is a good place to put this documentation, and it would be nice to build them from the tree. Some pages may need more information than just what is in the schema, so we should figure out where to put that.

We could also add more in-tree documentation, similar to firefox-source-docs but at our own URL.

Comment 7

[Eric Shepherd [:sheppy]]

In-tree documentation is always helpful, and RTD is a great place as well. I also don't see a problem with including links on MDN to the appropriate Thunderbird documentation in, for instance, the "See also" section of a page, and we encourage linking to MDN from the Thunderbird documentation when the existing material will get the job done.

Indeed, making use of MDN in those ways is likely to improve exposure for the Thunderbird documentation, and in theory would be beneficial for MDN as well, although in a much smaller way.

Comment 8

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/fae04892480f
Minor changes to addressBook API documentation; r=me

Comment 9

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/6689956229af
Fix some markup references in windows API docs; r=me DONTBUILD

Comment 10

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/7144956c64ee
Fix broken references in documentation; rs=docs-only

Comment 11

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/c145816dfef3
Improve some accounts API documentation; rs=docs-only

Comment 12

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/75b06e876544
Improve some addressBook API documentation; rs=docs-only

Comment 13

[Geoff Lankow (:darktrojan)]

There's really no need for this bug to remain open.