A documentation generator for Python code (replaces epydoc) | Hacker News Reader

A documentation generator for Python code (replaces epydoc)

github.com

9 pointsburntsushi4 comments

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.)

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 (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...

[2] - https://bitbucket.org/birkenfeld/sphinx/issue/904/autodocs-d...

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

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

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

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

[7] - https://github.com/BurntSushi/nfldb/blob/master/nfldb/types....

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/

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

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

> 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/

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. :-)

Reply on news.ycombinator.com