Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
Using sphinx to document mozbase
10 views
Skip to first unread message
William Lachance
Oct 12, 2012, 3:52:19 PM10/12/12
to mozill...@lists.mozilla.org, Jonathan Griffin, Jeff Hammel
So after being very impressed with some of the nice documentation
available on readthedocs that were built for the spade project
(http://spade.readthedocs.org/en/latest/index.html) using Sphinx
(http://sphinx.pocoo.org), I decided to have a look and see if we
couldn't use something similar for documenting mozbase.
After about an hour of poking around, I'm happy to report that it looks
like we should be able to fairly easily. :) Sphinx works pretty out of
bounds from your project and has quite a bit of flexibility as to how it
generates documentation based on source files. It is capable of pulling
in comment/class docstrings into documentation arbitrarily based on the
insertion of specific tags like this:
.. automodule:: mozdevice
.. autoclass:: mozdevice.DeviceManager
:members:
This allows the author to embed the class/method documentation around
specific intuitive explanations and background information, in whatever
organization they prefer. This strikes me as a much better approach than
just arbitrarily generating pages and pages of baffling documentation
about class hierarchies.
In the case of mozbase, we would write roughly a page per module.
Pulling in the documentation is simple, all you need to do is add each
source directory you're interested in to your path. For example, to get
the aforementioned mozdevice documentation, I added the following to
sphinx's conf.py (located in a just-created docs/ directory off the
repository root):
sys.path.insert(0, os.path.abspath('../mozinfo'))
sys.path.insert(0, os.path.abspath('../mozprocess'))
sys.path.insert(0, os.path.abspath('../mozdevice'))
(mozinfo and mozprocess were required because they are deps of mozdevice)
As I mentioned a few weeks ago, this is something I'd like to hack on
during the ateam work week's community days if people were interested.
Writing documentation is a great way to get familiar with mozbase and
make a measurable impact on the usability of our tools. :)
If this approach sounds cool to people, I'll probably get things started
next week with the addition of a basic docs/ directory in mozbase and
the documentation of one simple module (maybe mozfile?) to use as a
further example. Then during the work week we can continue by:
* Adding new documentation pages for other mozbase modules
* Adding/modifying docstrings for mozbase modules so they look great
inside our documentation (this will probably have the happy side effect
of improving our source level documentation)
Will
available on readthedocs that were built for the spade project
(http://spade.readthedocs.org/en/latest/index.html) using Sphinx
(http://sphinx.pocoo.org), I decided to have a look and see if we
couldn't use something similar for documenting mozbase.
After about an hour of poking around, I'm happy to report that it looks
like we should be able to fairly easily. :) Sphinx works pretty out of
bounds from your project and has quite a bit of flexibility as to how it
generates documentation based on source files. It is capable of pulling
in comment/class docstrings into documentation arbitrarily based on the
insertion of specific tags like this:
.. automodule:: mozdevice
.. autoclass:: mozdevice.DeviceManager
:members:
This allows the author to embed the class/method documentation around
specific intuitive explanations and background information, in whatever
organization they prefer. This strikes me as a much better approach than
just arbitrarily generating pages and pages of baffling documentation
about class hierarchies.
In the case of mozbase, we would write roughly a page per module.
Pulling in the documentation is simple, all you need to do is add each
source directory you're interested in to your path. For example, to get
the aforementioned mozdevice documentation, I added the following to
sphinx's conf.py (located in a just-created docs/ directory off the
repository root):
sys.path.insert(0, os.path.abspath('../mozinfo'))
sys.path.insert(0, os.path.abspath('../mozprocess'))
sys.path.insert(0, os.path.abspath('../mozdevice'))
(mozinfo and mozprocess were required because they are deps of mozdevice)
As I mentioned a few weeks ago, this is something I'd like to hack on
during the ateam work week's community days if people were interested.
Writing documentation is a great way to get familiar with mozbase and
make a measurable impact on the usability of our tools. :)
If this approach sounds cool to people, I'll probably get things started
next week with the addition of a basic docs/ directory in mozbase and
the documentation of one simple module (maybe mozfile?) to use as a
further example. Then during the work week we can continue by:
* Adding new documentation pages for other mozbase modules
* Adding/modifying docstrings for mozbase modules so they look great
inside our documentation (this will probably have the happy side effect
of improving our source level documentation)
Will
Jonathan Griffin
Oct 12, 2012, 5:40:34 PM10/12/12
to William Lachance, Jeff Hammel
Nice, seems like this is the best of both worlds: nice in-source docs
plus an easy, searchable UI.
Jonathan
plus an easy, searchable UI.
Jonathan
William Lachance
Oct 22, 2012, 4:11:24 PM10/22/12
to mozill...@lists.mozilla.org, Jonathan Griffin, Jeff Hammel
On 10/12/2012 03:52 PM, William Lachance wrote:
> So after being very impressed with some of the nice documentation
> available on readthedocs that were built for the spade project
> (http://spade.readthedocs.org/en/latest/index.html) using Sphinx
> (http://sphinx.pocoo.org), I decided to have a look and see if we
> couldn't use something similar for documenting mozbase.
>
> ...
> So after being very impressed with some of the nice documentation
> available on readthedocs that were built for the spade project
> (http://spade.readthedocs.org/en/latest/index.html) using Sphinx
> (http://sphinx.pocoo.org), I decided to have a look and see if we
> couldn't use something similar for documenting mozbase.
>
Ok, so I didn't see any strong objections to using this approach to
document mozbase. To get the ball rolling, I filed a bug
(https://bugzilla.mozilla.org/show_bug.cgi?id=804300) to add a first cut
of documentation to mozbase. I also scheduled in a project to work on
this during the a-team's community hack days during our meetup in Toronto:
https://wiki.mozilla.org/Auto-tools/Meetups/Toronto2012#Documentation_Sprint:_Documenting_Mozbase
If you're interested in participating in such a thing remotely, just
show up on irc #ateam sometime on Friday and/or Saturday this week
during EST working hours. With luck, we'll be able to find something for
you to do. :)
Will
William Lachance
Oct 22, 2012, 4:11:24 PM10/22/12
to mozill...@lists.mozilla.org, mozill...@lists.mozilla.org, Jonathan Griffin, Jeff Hammel
On 10/12/2012 03:52 PM, William Lachance wrote:
> So after being very impressed with some of the nice documentation
> available on readthedocs that were built for the spade project
> (http://spade.readthedocs.org/en/latest/index.html) using Sphinx
> (http://sphinx.pocoo.org), I decided to have a look and see if we
> couldn't use something similar for documenting mozbase.
>
> available on readthedocs that were built for the spade project
> (http://spade.readthedocs.org/en/latest/index.html) using Sphinx
> (http://sphinx.pocoo.org), I decided to have a look and see if we
> couldn't use something similar for documenting mozbase.
>
0 new messages