nfldb

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