

A documentation generator for Python code (replaces epydoc) - burntsushi
https://github.com/BurntSushi/pdoc/blob/master

======
stevejohnson
This is a neat project (I used to use epydoc myself), but Sphinx just isn't
that hard to set up with sphinx-quickstart, and sphinx-apidoc takes care of
autogenerating docs without any extra files at all.

I do not mean to be discouraging. I like the output of pdoc, and any tool that
increases the amount of documentation where there would otherwise be none is
great in my book. I simply recommend that you try to understand Sphinx a
little better before claiming superiority. In my opinion, pdoc's real
advantage is that it requires essentially zero setup and is probably easier to
understand. (You should recognize, though, that sphinx-apidoc also requires
zero setup.)

~~~
burntsushi
Allow me to apologize in advance for a reply whose length isn't warranted by
your comment. While you aren't the first to mention "just use Sphinx man" to
me, you are the first who has spurred me into giving a concrete reply. With
that said, don't think lower of me for my rant, please. :-)

> but Sphinx just isn't that hard to set up with sphinx-quickstart, and
> sphinx-apidoc takes care of autogenerating docs without any extra files at
> all.

I very very very strongly disagree. I was pretty short in my GitHub README
because I didn't want to turn it into a rant about Sphinx, but I can assure
you that I've tried. Ever since I started documenting my Python code a few
years ago, I was given two choices: epydoc and Sphinx. Couldn't get Sphinx to
work, but with enough massaging, epydoc produced something that I found usable
(even though it visually offended me).

Since then, I would annually get sick of `epydoc` and try out Sphinx again to
see if things improved. I remember when `sphinx-apidoc` was added and thought
it would solve all my problems. It didn't. For example, if I run `sphinx-
apidoc` on my `pdoc` module, this is what I get in `pdoc.rst`:

    
    
        pdoc Module
        ===========
        
        .. automodule:: pdoc
            :members:
            :undoc-members:
            :show-inheritance:
    

Hmm. OK? That wasn't what I was expecting, but the words "auto" seem
promising. I run the necessary `make html` and look at the output:
[http://burntsushi.net/stuff/pdoc-sphinx](http://burntsushi.net/stuff/pdoc-
sphinx) (ignore the Markdown ugliness, I would be willing to live with RST).

Seems plausible. But wait. My representation isn't documented! Dammit. So I
look up the documentation for the `autodoc` extension. I find things like
`autoattribute`[1] and an undocumented `autoinstanceattribute`[2] that look
promising. But god dammit, I have to write `autoattribute` for each attribute
I want to document. I googled for something that would do it for me (and
looked at `sphinx-apidoc` more closely for relevant options). Maybe it exists,
but I couldn't find anything. And the comments for the bug in [2] don't give
me any hope either (where each attribute is delineated).

Now I guess I could have written something that generates a Sphinx `rst` file
with all the right `autoattribute` commands, but at this point, I'm drowning.
After getting fed up with epydoc's own weird rules for documenting module and
class variables, and its inability to look in `__init__` for instance
variables, I had enough. To put a cherry on top of this, I've been spoiled by
Go's automatic documentation[3] that you _literally_ get for free. You can
generate documentation on the fly for any Go project[4]---no config files, no
running commands to make HTML, nothing. Just an import path and some simple
conventions.

So I threw my hands up, proclaimed that I didn't deserve to be treated the way
Sphinx treated me, and wrote my own in about ~6 days. It was harder than I
anticipated, but now that it's done, I'm totally loving my choice to do it.

You may note that there are other ways to document instance variables like
`:ivar:` that both epydoc and Sphinx support. That's just a giant hack to me
and is completely and utterly incompatible with generating documentation on
the fly. For example, in one of my Python modules that requires a lot of
attributes[5], it's practically suicide not to have a single point of
truth[6]. Solution to that? A very simple convention that I haven't seen used
in epydoc or Sphinx.[7] Maybe it exists, I'm not sure. (Don't you dare tell me
to append to `__doc__` dynamically!)

Basically, `pdoc`'s gimmick is that it can generate API docs for _any_ module
on the fly if you run it as an HTTP server. Since it adheres to common
conventions used to document module/class/instance variables, it can pick
those up. Oh, and it makes it simple to reference other public members of
other modules. Which I use All. The. Time. Love it. (I'm sure Sphinx has this
too...)

> I simply recommend that you try to understand Sphinx a little better before
> claiming superiority.

I have to respond to this. Even with my all my ranting, I really and _truly_
do not believe pdoc is superior. I certainly believe it is superior _for me_ ,
but I understand that people have different workflows. For example, I
generally don't have too much of a problem following Sphinx documentation for
other projects, although they can be difficult to navigate if the author isn't
conscious about providing the right links in obvious places.

> (You should recognize, though, that sphinx-apidoc also requires zero setup.)

See above. Am I wrong with having to write out all the `autoattribute` stuff?
If I am, that does make Sphinx marginally better. Not sure if it would have
stopped me, though. (Because of all the other stuff I mentioned.)

[1] - [http://sphinx-doc.org/ext/autodoc.html#directive-
autoattribu...](http://sphinx-doc.org/ext/autodoc.html#directive-
autoattribute)

[2] -
[https://bitbucket.org/birkenfeld/sphinx/issue/904/autodocs-d...](https://bitbucket.org/birkenfeld/sphinx/issue/904/autodocs-
does-not-work-well-with-instance)

[3] - [http://golang.org/pkg](http://golang.org/pkg)

[4] -
[http://godoc.org/github.com/BurntSushi/toml](http://godoc.org/github.com/BurntSushi/toml)

[5] -
[http://pdoc.burntsushi.net/nfldb#nfldb.Play](http://pdoc.burntsushi.net/nfldb#nfldb.Play)

[6] -
[https://github.com/BurntSushi/nfldb/blob/master/nfldb/data-d...](https://github.com/BurntSushi/nfldb/blob/master/nfldb/data-
dictionary.csv)

[7] -
[https://github.com/BurntSushi/nfldb/blob/master/nfldb/types....](https://github.com/BurntSushi/nfldb/blob/master/nfldb/types.py#L645)

~~~
stevejohnson
You found me out: I haven't actually tried to use sphinx-apidoc. Its help page
seems to imply that it actually generates all the output HTML, not just a
prefab Sphinx dir. Sorry for spreading misinformation.

You do have very good reasons for wanting a separate tool (or at the very
least, for improving Sphinx's behavior for this use case). I think you can
make those reasons clear in your docs without causing the sort of confusion I
had. In my mind, pdoc's advantages are that (1) there really is no need for
file-based configuration, and (2) (now that you've told me) it has superior
discovery of instance variables. The hand-waving "I couldn't configure it"
doesn't work in your favor.

I'm no stranger to how bad/strange Sphinx can be; I work on this:
[https://sphinx-better-theme.readthedocs.org/en/latest/](https://sphinx-
better-theme.readthedocs.org/en/latest/)

and I work with it a _lot_ to write the docs for this project:
[http://mrjob.readthedocs.org/en/latest/](http://mrjob.readthedocs.org/en/latest/)

and it's generally a monster to figure out the internals of.

~~~
burntsushi
> I think you can make those reasons clear in your docs without causing the
> sort of confusion I had. ... The hand-waving "I couldn't configure it"
> doesn't work in your favor.

Excellent suggestion. I'm still full of emotion after writing that rant, but
when I calm down, I'll try and craft a section on "Why Not Sphinx" in my
README. It's quite literally the only criticism I've received so far. I'll
keep your interpretation of pdoc's advantages in mind.

> and I work with it a lot to write the docs for this project:
> [http://mrjob.readthedocs.org/en/latest/](http://mrjob.readthedocs.org/en/latest/)

You have my compliments. That is really beautiful (in every sense)
documentation---you are clearly not among those who aren't conscious of
putting links in obvious places. :-)

