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