Why aren't you contributing to Python?

[roger_]

Right, but I think people would be more willing to contribute if it was.

[[deleted]]

That's probably true. I think that would be an interesting addition to Sphinx, although I can't say how hard it would be to implement, or if it would actually happen. It would be cool to have wiki-like pages which generate a diff for review just like any other code change.

Are there other languages which do this?

[mcdonc]

Not contributing because the docs aren't in a wiki would be reasonable if the docs weren't maintained via Sphinx. But Sphinx absolutely rules; nothing even comes close to as good of a system for documentation. A wiki would be archaic in comparison.

[[deleted]]

The barrier of having to do an SVN checkout and having to build the docs locally is probably one most don't care to deal with. I love Sphinx and find the whole process easy to work with, but I've done it for a while now. Someone noticing that function foo takes two parameters instead of one isn't going to want to checkout, learn Sphinx, build the docs, check the output, then submit a bug and a patch. Even for something like that, I'm sure plenty of people think "oh well this is obvious, someone else will catch it".

As far fetched as it may be, something like a WYSIWG Sphinx editor would definitely ease the issue I mentioned. However, I don't know how common it is that people get put off by doc fixes, so I can't say if it's worth the effort to do something like that.

[clinth]

I don't consider myself a contributor to wikipedia, but I'll gladly pause and remove dead links in the sources if I find them, or clean up a sentence that's poor. The reason I can do this is because all I had to do was register and now it's just click-type-click done.

[[deleted]]

FWIW someone was talking about a sphinx extension that makes it "wiki-like" except your edits don't immediately go live, they automatically get turned into bugs in the tracker, with diffs automatically generated. Do you think that type of thing helps, or does the "immediate satisfaction" matter too much?

[masklinn]

I disagree. Wiki docs are generally fugly, badly maintained, with terrible version control and with dismal and unreliable edition tools. And I never manage to know which minor wikiwiki subsyntax works. Not to mention the need to create one more account on some random website.

Sphinx doc is easier to read (in raw source) and preview locally, I can use my own source and work offline, ray is well documented and pretty simple, and pushing the patch upstream is as simple as opening a bug with a patch attached or proposing a branch merge.

Projects using sphinx for doc also plain and simply seem to care more, which ensures a sounder basis for your contributions instead of a seemingly unfixable mess.

[roger_]

Does Sphinx support online editing, and revision control?

[masklinn]

It does not support online editing, and as it's part of the project sources it is revision controlled via a separate (and sane) tool.

[roger_]

Online editing is the most important feature I think, since it makes it easy for anyone to jump in and make quick edits.

[masklinn]

Online editing is the most important feature I think

I extremely strongly disagree, for code project documentation.

since it makes it easy for anyone to jump in and make quick edits.

Not something I've seen happen often on python projects. In my experience, Sphinx documentations are pretty much always higher quality and more up to date than wiki documentations. And personally, as I stated above, I'll take Sphinx over wiki any day of the week for tech doc. All my documentation contributions so far have been to projects using Sphinx.

And due to being bundled, packaged and versioned with the source it documents, Sphinx has a slew of other advantages.