4 ms·
It's strange to see this is your experience, because I had the exact opposite: Python documentations are usually very comprehensive, nicely formatted. Important
by kissgyorgy 8y ago
It's strange to see this is your experience, because I had the exact opposite: Python documentations are usually very comprehensive, nicely formatted. Important projects have very good documentations and setting up a new documentation is very easy with Sphinx. Maybe you should try it again, it might have changed a lot since you looked it.
- peteretep 8y agoI 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.
- jefftk 8y agoHow would you want this to work? The alternatives to Sphinx I've used (Javadoc, Doxygen) more or less work the same way.
- mjw1007 8y agoI 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.
- kissgyorgy 8y agoI 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.
- peteretep 8y agoExactly on the money. I want to document my library, not create a website.
- corv 8y agoHaving just had the pleasure of using Sphinx for the first time, I can only underline what you wrote.