853956 - mozhttpd doc additions/improvements

Status: RESOLVED FIXED

(Testing :: Mozbase, defect)

Description

[William Lachance (:wlach)]

Chris Manchester made a great start on mozhttpd documentation at the ateam workweek last fall, but there's IMO still room for improvement. In particular, it would be great to have some example code on how to use the thing.

Comment 1

[William Lachance (:wlach)]

Attachment: Doc improvements + example

Comment 2

[Jeff Hammel]

Comment on attachment 728348 [details] [diff] [review]
Doc improvements + example

r+ with concerns.

While I'm generally all for more+better documentation, and assuredly having documentation in python docstrings makes for a very streamlined development experience, I do question putting too much in docstrings.  For example, the example usages in __init__.py ... are probably fine.  But to me, and it's mostly opinion, these feel like they belong in documentation about the code vs documentation in the code.  So there is the dilemma of wanting to generate as much as possible documentation from the code vs not overburdening the code with documentation. I've dealt with code that had so much in-docstring documentation that it became burdensome to read the source files, and that's something I'd like to avoid (while of course providing developers with as much documentation as they actually need in situ and pointing to more thorough docs when available).

I also generally dislike ReST (or other markdown flavors) in docstrings or elsewhere that don't eye-parse.  To me, and I realize my POV is different from others who think of markdown as "a way to save typing", the point of ReST/markdown is to provide text that reads naturally *and* can be converted to HTML or other nice thing.

To that end:

+content from the current directory, defines a single API endpoint
+`/api/resource/<resourceid>` and then serves requests indefinitely:
+
+::
+
+  import mozhttpd

I believe if you end a paragraph in a `::` you do not need to have a separate `::` line to denote a literal block in ReST.  In other notes, `/api/resource/<resourceid>` ... you need double `` to escape in ReST (which I think is stupid for the very "read naturally" point I raise above, but ReST makes (over)use of grave quotes for internals).

Anyway, just something to get you thinking.  I think the patch can and should be taken as is as we can always refine this moving forward.

Comment 3

[William Lachance (:wlach)]

(In reply to Jeff Hammel [:jhammel] from comment #2)
> Comment on attachment 728348 [details] [diff] [review]
> Doc improvements + example
> 
> r+ with concerns.
> 
> While I'm generally all for more+better documentation, and assuredly having
> documentation in python docstrings makes for a very streamlined development
> experience, I do question putting too much in docstrings.  For example, the
> example usages in __init__.py ... are probably fine.  But to me, and it's
> mostly opinion, these feel like they belong in documentation about the code
> vs documentation in the code.  So there is the dilemma of wanting to
> generate as much as possible documentation from the code vs not
> overburdening the code with documentation. I've dealt with code that had so
> much in-docstring documentation that it became burdensome to read the source
> files, and that's something I'd like to avoid (while of course providing
> developers with as much documentation as they actually need in situ and
> pointing to more thorough docs when available).

Yes, it's a tricky balance. Putting main module documentation in __init__ seems to be a fairly standard practice though. I think most of mozbase is simple enough that it'll wind up being ok.

> I also generally dislike ReST (or other markdown flavors) in docstrings or
> elsewhere that don't eye-parse.  To me, and I realize my POV is different
> from others who think of markdown as "a way to save typing", the point of
> ReST/markdown is to provide text that reads naturally *and* can be converted
> to HTML or other nice thing.
> 
> To that end:
> 
> +content from the current directory, defines a single API endpoint
> +`/api/resource/<resourceid>` and then serves requests indefinitely:
> +
> +::
> +
> +  import mozhttpd
> 
> I believe if you end a paragraph in a `::` you do not need to have a
> separate `::` line to denote a literal block in ReST.  In other notes,
> `/api/resource/<resourceid>` ... you need double `` to escape in ReST (which
> I think is stupid for the very "read naturally" point I raise above, but
> ReST makes (over)use of grave quotes for internals).

Hmm, unfortunately sphinx doesn't seem to understand that syntax: if I remove the `::`, I don't get the code formatting when the docs are generated.

For me, using the various features of .rst is more a means to an end: generating nice-looking documentation for our site http://mozbase.readthedocs.org. I expect that most of the time that's where this stuff is going to be read. That said, I agree with not making our documentation hard to read gratuitously.

Comment 4

[William Lachance (:wlach)]

Pushed: https://github.com/mozilla/mozbase/commit/e3b5b05e877102b905096988f536cd25b5a841fb