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.

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.

Having just had the pleasure of using Sphinx for the first time, I can only underline what you wrote.

Some python documentation conventions are weird, to be sure. But I’d rather have an eternity of Sphinx build toolchains than the hell that is making POD/Perldoc work for medium-to-large projects (or small ones, for that matter).

> the hell that is making POD/Perldoc work for medium-to-large projects

Such as?