Hacker News new | past | comments | ask | show | jobs | submit login

I looked at it last a month ago. It was terrible.

> setting up a new documentation is very easy with Sphinx

As per my original comment, the idea that documentation should require some kind of external markdown static site generator is bizarro land.




How would you want this to work? The alternatives to Sphinx I've used (Javadoc, Doxygen) more or less work the same way.


I think there's a big difference.

Sphinx starts from the point of view that you're going to write your documentation as if you were writing a book, then on top of that it has some optional features for pulling in information from source files.

Most of the others start from the view that you're autogenerating documentation from source-code comments, and on top of that there are some optional features for pulling in some extra content from documentation-specific files.

I think the Sphinx way tends to produce better documentation in the long run, but it takes more effort to get to something just-about-adequate.


I understand your point, and Go is probably better in this regard, but it's pretty easy to get started with Sphinx with autogenerating documentation from code. You don't have to manually write anything.


Exactly on the money. I want to document my library, not create a website.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: