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.
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/
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?
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.
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. :)
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)
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.
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?
(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.
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.