If you think a bug might affect users in the 57 release, please set the correct tracking and status flags for Release Management.

Generate documentation from source code and publish to readthedocs.org

RESOLVED FIXED

Status

Firefox OS
Gaia::UI Tests
RESOLVED FIXED
3 years ago
3 years ago

People

(Reporter: davehunt, Assigned: davehunt)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

Attachments

(1 attachment)

(Assignee)

Description

3 years ago
The API for gaiatest is not currently documented, which reduces visibility and increases the barrier for entry when working on the harness or related tests. We should use readthedocs.org like we have for mozbase to provide constantly up to date documentation.
(Assignee)

Comment 1

3 years ago
Created attachment 8455265 [details] [review]
Link to Github pull-request: https://github.com/mozilla-b2g/gaia/pull/21690

Note that the docstrings are rather lacking. We should probably file additional bugs to improve these throughout the project. A preview is available here: http://gaiatest.readthedocs.org/en/latest/
Attachment #8455265 - Flags: review?(zcampbell)
Attachment #8455265 - Flags: review?(wlachance)
(Assignee)

Comment 2

3 years ago
I'd rather not have to maintain references to the modules we want to document. I tried a couple of different things to see if I could get autodoc to pick these up automatically but was unsuccessful. Will: Do you have any thoughts on how we might do this?
Flags: needinfo?(wlachance)
Unfortunately I don't think there's any way to avoid specifically references the modules you want to document via declarations like ".. automodule:: gaiatest.apps.messages.regions.activities". :( We'll have to be vigilant when reviewing patches to keep this stuff up to date.
Flags: needinfo?(wlachance)
Comment on attachment 8455265 [details] [review]
Link to Github pull-request: https://github.com/mozilla-b2g/gaia/pull/21690

I'd be pretty happy to see this go in as-is, I didn't do a close of review of the actual gaiatest stuff as I'm not that familiar with it. I'm trusting :zac to look into that. :)
Attachment #8455265 - Flags: review?(wlachance) → review+

Comment 5

3 years ago
Comment on attachment 8455265 [details] [review]
Link to Github pull-request: https://github.com/mozilla-b2g/gaia/pull/21690

Yeah shame it's not 100% automated but it's a better step than current.

I see lots of places we can make tweaks to the docs but that's way outside the scope of this; we'll have to follow up with a few bugs.

Thanks Dave.

r+  (with that MDN link change if you want to)
Attachment #8455265 - Flags: review?(zcampbell) → review+
(Assignee)

Comment 6

3 years ago
Landed in:
https://github.com/mozilla-b2g/gaia/commit/48fe31ffcd3b9eca4eeb13cd0a73c1a28b45b295

Released as:
http://gaiatest.readthedocs.org/en/latest/
(Assignee)

Comment 7

3 years ago
jgriffin: As a github admin, could you set up a webhook so that we build and publish the documentation whenever there's an update? See https://docs.readthedocs.org/en/latest/webhooks.html#github for instructions.
Flags: needinfo?(jgriffin)
I know we had to be careful about doing this with Marionette, because the volume of commits to mozilla-central was high and not very friendly for readthedocs server.  I suspect we could have the same issue with anything in the Gaia repo.

Will, how did we address this issue with the Marionette docs?
Flags: needinfo?(wlachance)
(In reply to Jonathan Griffin (:jgriffin) from comment #8)
> I know we had to be careful about doing this with Marionette, because the
> volume of commits to mozilla-central was high and not very friendly for
> readthedocs server.  I suspect we could have the same issue with anything in
> the Gaia repo.
> 
> Will, how did we address this issue with the Marionette docs?

I thought this might be a problem, but in practice we never had a webhook for marionette; we always just generated the docs manually. I've since learned a bit more about readthedocs' architecture and I think gaia should not really be that big a deal. Updating the docs should be quite cheap as it keeps a cached copy of the gaia repo checked out.
Flags: needinfo?(wlachance)
Hook added.
Flags: needinfo?(jgriffin)
(Assignee)

Updated

3 years ago
Status: ASSIGNED → RESOLVED
Last Resolved: 3 years ago
Resolution: --- → FIXED
Why not having kept a local copy of the doc generated ? It's painful to have to connect to another website just to know how to setup/run the system, when you already have the git clone locally.
You need to log in before you can comment on or make changes to this bug.