804300 - Use sphinx to add documentation to mozbase

Status: RESOLVED FIXED

(Testing :: Mozbase, defect)

Description

[William Lachance (:wlach)]

As discussed on the tools mailing list a bit over a week ago, I'd like to use sphinx to document mozbase, for three reasons:

1. We can automatically generate great documentation from python method signatures (which in turn encourages writing good python method signatures)
2. The generated documentation looks great.
3. You can automatically set up readthedocs to generate great-looking searchable documentation which we can link to from elsewhere.

Comment 1

[William Lachance (:wlach)]

Attachment: Beginnings of a sphinx-based documentation approach

This gets the ball rolling. There are a few caveats and such, which is why I am asking for feedback rather than a review:

1. None of the existing documentation (e.g. manifestdestiny) has been ported over to the new format.
2. The introductory text is just a stub.
3. We should figure out the relationship of the documentation with the module-based descriptions that are currently stored as README.md for each module. To make sure that we don't have to duplicate this text, maybe we should convert these into .rsts and then import the brief descriptions into our documentation when we build it?

Doubtless there are other things that could be improved too. If this looks ok, I'd like to convert over the existing documentation, fix any nits, then mark that as the first version which we can then improve during the community hack day.

Comment 2

[William Lachance (:wlach)]

Comment on attachment 673976 [details] [diff] [review]
Beginnings of a sphinx-based documentation approach

As discussed, let's aim to land this patch (or a variant of it with minor nits addressed) later today or early tomorrow while documenting any deficiencies and fixing them quickly in a follow-up bug.

Comment 3

[Jeff Hammel]

Comment on attachment 673976 [details] [diff] [review]
Beginnings of a sphinx-based documentation approach

+docs/_build/*

Doesn't just docs/_build work here?  Perhaps even .docs/_* or .docs/_templates etc

+sys.path.insert(0, os.path.abspath('../mozfile'))

It'd be nice to do this dynamically.  That or we can just insist that e.g. setup_development.py is run

Looks good.  A helluva lot better than what we have currently.  How will this post to readthedocs?

Comment 4

[William Lachance (:wlach)]

(In reply to Jeff Hammel [:jhammel] from comment #3)
> Comment on attachment 673976 [details] [diff] [review]
> Beginnings of a sphinx-based documentation approach
> 
> +docs/_build/*
> 
> Doesn't just docs/_build work here?  Perhaps even .docs/_* or
> .docs/_templates etc

Yeah, I just fixed this to just say docs/_build

> +sys.path.insert(0, os.path.abspath('../mozfile'))
> 
> It'd be nice to do this dynamically.  That or we can just insist that e.g.
> setup_development.py is run

Yep, not quite sure the best way of doing that though so I guess we can do that as a followup?
 
> Looks good.  A helluva lot better than what we have currently.  How will
> this post to readthedocs?

Don't know yet. :) We will figure it out though.

Comment 5

[William Lachance (:wlach)]

https://github.com/mozilla/mozbase/commit/f0876d12eea9d0bcf4797b37b3f5f70a13900eb6

Comment 6

[Jeff Hammel]

(In reply to William Lachance (:wlach) from comment #4)
> (In reply to Jeff Hammel [:jhammel] from comment #3)
> > Comment on attachment 673976 [details] [diff] [review]
> > Beginnings of a sphinx-based documentation approach
> > 
> > +docs/_build/*
> > 
> > Doesn't just docs/_build work here?  Perhaps even .docs/_* or
> > .docs/_templates etc
> 
> Yeah, I just fixed this to just say docs/_build

coolz

> > +sys.path.insert(0, os.path.abspath('../mozfile'))
> > 
> > It'd be nice to do this dynamically.  That or we can just insist that e.g.
> > setup_development.py is run
> 
> Yep, not quite sure the best way of doing that though so I guess we can do
> that as a followup?

So I'm not entirely sure what the point of this line is.  If setup_development.py is run, this should already be available, right?  If not, you could do something like

parent = os.path.dirname(os.path.abspath(__file__))
for i in os.path.listdir(parent):
   path = os.path.join(parent, i)
   if os.path.isdir(path):
      sys.path.insert(0, path)
 
> > Looks good.  A helluva lot better than what we have currently.  How will
> > this post to readthedocs?
> 
> Don't know yet. :) We will figure it out though.