BMO-specific docs

[Gervase Markham]

This was discussed in this week's BMO meeting:

https://wiki.mozilla.org/BMO/Meetings/2015-03-10

I think BMO should:

* Upgrade to 5.0
* Point bmo.readthedocs.org at the BMO git repo

Done :-) Apart from the fact that that RTD doesn't pick up extension
docs because they are copied into the relevant places by the makedocs.pl
script. So you could either move them around on your branch only, or we
could find another way to include them properly.

Gerv

[Dave Lawrence]

That is the plan. As for extensions, I propose we use the makedocs.pl
command locally to copy the
extention rst files into the right place. And then git commit the new files
so that readthedocs.org will
include them properly. That means that we have to remember to do the extra
step whenever extension
docs have been changed but it probably will not happen that often.

dkl

> _______________________________________________
> tools-bmo mailing list
> tool...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/tools-bmo
>



--
David Lawrence
d...@mozilla.com
bugzilla.mozilla.org

[Gregory Szorc]

I'm not sure what your Sphinx/RTD setup looks like and if you are already
doing this, but it is possible to inject custom processing steps into
Sphinx so that RTD will render all your custom foo.

We do this for the mozilla-central docs:

https://hg.mozilla.org/mozilla-central/file/7d85ac833cff/tools/docs/conf.py
https://hg.mozilla.org/mozilla-central/file/7d85ac833cff/python/mozbuild/mozbuild/sphinx.py
https://hg.mozilla.org/mozilla-central/file/7d85ac833cff/tools/docs/moztreedocs/__init__.py

Essentially, the setup() for a custom extension invokes some Python that
does stuff. It's a hack. But a hack that works.

You /could/ do a lot of this inside your conf.py. We already had a Sphinx
extension for Firefox, so we just put the code in there.

[Byron Jones]

we spoke about this last night's meeting (gerv's email predates the
actual meeting where this agenda item was discussed).

while the greater plan does include upgrading to 5.0, it isn't a blocker
for generation of bmo-specific api documentation -- we need api docs
much sooner than we'd be able to upgrade to 5.0.

moving the duplication of the extension docs from makedocs.pl to conf.py
makes a lot of sense (thanks gps).



-glob

byron jones - :glob - bugzilla.mozilla.org team lead -

[Gervase Markham]

On 06/03/15 19:51, Gregory Szorc wrote:
> I'm not sure what your Sphinx/RTD setup looks like and if you are already
> doing this, but it is possible to inject custom processing steps into
> Sphinx so that RTD will render all your custom foo.

That's a great idea - thanks gps!

https://bugzilla.mozilla.org/show_bug.cgi?id=1144086

Gerv