1384517 - Generate Marionette server API documentation

Status: RESOLVED FIXED

(Remote Protocol :: Marionette, enhancement, P4)

Description

[Andreas Tolfsen ❲:ato❳]

Much of the Marionette server code in testing/marionette/*.js is
documented with useful type information.  It would be useful to
generate these docs using jsdoc (or equivalent).

When https://bugzilla.mozilla.org/show_bug.cgi?id=1381920 is fixed,
it will be possible to browse HTML documents on searchfox.org.  This
would make the generated API documentation self-hosting.

Comment 1

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Render Marionette README as HTML;

To include the Marionette server README in the generated API
documentation, we need to provide some semantic rules describing the
document structure.

searchfox.com will soon also be able to render HTML documents inline,
making it possible to browse testing/marionette/README.html directly
from the source browser.

Review commit: https://reviewboard.mozilla.org/r/161500/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161500/

Comment 2

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Provide jsdoc rules for testing/marionette;

Review commit: https://reviewboard.mozilla.org/r/161502/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161502/

Comment 3

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Fix testing/marionette API docs;

Various fixes to make the generated API documentation from
testing/marionette somewhat easier to read.

Review commit: https://reviewboard.mozilla.org/r/161504/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161504/

Comment 4

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Add "marionette doc" subcommand to generate docs;

This patch introduces a new top-level mach command "marionette" that
can be invoked as `./mach marionette`.  It offers two subcommands,
"test" and "doc".

The "test" subcommand is functionally equivalent to the existing
"marionette-test" command, which this patch deprecates.

The "doc" subcommand generates the Marionette server API documentation
using jsdoc, which it is presumed is already installed on the system.
A future patch will make this subcommand more sophisticated, but this
should work for now.

It also comes with an --http <host>:<port> flag which spins up an HTTPD
serving the documentation.

Review commit: https://reviewboard.mozilla.org/r/161506/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161506/

Comment 5

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Exclude testing/marionette/doc from linting;

It also lists directories instead of globbing all files.

Review commit: https://reviewboard.mozilla.org/r/161508/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161508/

Comment 6

[Andreas Tolfsen ❲:ato❳]

Attachment: Bug 1384517 - Generate Marionette server API docs;

This is automatically generated from `./mach marionette doc`.

Review commit: https://reviewboard.mozilla.org/r/161510/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/161510/

Comment 7

[David Burns :automatedtester]

Comment on attachment 8890382 [details]
Bug 1384517 - Render Marionette README as HTML;

https://reviewboard.mozilla.org/r/161500/#review166984

Comment 8

[David Burns :automatedtester]

Comment on attachment 8890383 [details]
Bug 1384517 - Provide jsdoc rules for testing/marionette;

https://reviewboard.mozilla.org/r/161502/#review166988

Comment 9

[David Burns :automatedtester]

Comment on attachment 8890384 [details]
Bug 1384517 - Fix testing/marionette API docs;

https://reviewboard.mozilla.org/r/161504/#review167000

Comment 10

[David Burns :automatedtester]

Comment on attachment 8890385 [details]
Bug 1384517 - Add "marionette doc" subcommand to generate docs;

https://reviewboard.mozilla.org/r/161506/#review167016

Comment 11

[David Burns :automatedtester]

Comment on attachment 8890386 [details]
Bug 1384517 - Exclude testing/marionette/doc from linting;

https://reviewboard.mozilla.org/r/161508/#review167018

Comment 12

[David Burns :automatedtester]

Comment on attachment 8890386 [details]
Bug 1384517 - Exclude testing/marionette/doc from linting;

https://reviewboard.mozilla.org/r/161508/#review167028

r+ but this is more of I assume this is correct since its autogenerated.

Comment 13

[David Burns :automatedtester]

Comment on attachment 8890387 [details]
Bug 1384517 - Generate Marionette server API docs;

https://reviewboard.mozilla.org/r/161510/#review167030

Comment 14

[David Burns :automatedtester]

Comment on attachment 8890386 [details]
Bug 1384517 - Exclude testing/marionette/doc from linting;

https://reviewboard.mozilla.org/r/161508/#review167034

Comment 15

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/6a61f3b97e51
Render Marionette README as HTML; r=automatedtester
https://hg.mozilla.org/integration/autoland/rev/9c46b91899fa
Provide jsdoc rules for testing/marionette; r=automatedtester
https://hg.mozilla.org/integration/autoland/rev/c530d257c6d2
Fix testing/marionette API docs; r=automatedtester
https://hg.mozilla.org/integration/autoland/rev/31dcb89c3c4b
Add "marionette doc" subcommand to generate docs; r=automatedtester
https://hg.mozilla.org/integration/autoland/rev/cba13cf446d5
Exclude testing/marionette/doc from linting; r=automatedtester
https://hg.mozilla.org/integration/autoland/rev/9092331c31e4
Generate Marionette server API docs; r=automatedtester

Comment 16

[Carsten Book [:Tomcat]]

https://hg.mozilla.org/mozilla-central/rev/6a61f3b97e51
https://hg.mozilla.org/mozilla-central/rev/9c46b91899fa
https://hg.mozilla.org/mozilla-central/rev/c530d257c6d2
https://hg.mozilla.org/mozilla-central/rev/31dcb89c3c4b
https://hg.mozilla.org/mozilla-central/rev/cba13cf446d5
https://hg.mozilla.org/mozilla-central/rev/9092331c31e4

Comment 18

[Henrik Skupin [:whimboo][⌚️UTC+2]]

Andreas, thanks for the work here! I assume that we have to make it common for us now to manually run this command whenever we change the API of Marionette server? So there is also no service like readthedocs out there, which would do it automatically for us?

Comment 19

[Andreas Tolfsen ❲:ato❳]

(In reply to Henrik Skupin (:whimboo) from comment #18)

> Andreas, thanks for the work here! I assume that we have to make
> it common for us now to manually run this command whenever we
> change the API of Marionette server? So there is also no service
> like readthedocs out there, which would do it automatically for
> us?

See my email to tools-marionette@:

	https://groups.google.com/d/msg/mozilla.tools.marionette/aRImw7eq1IA/iaJNZzTXAwAJ