[Ironpython-users] IronPython Documentation (was: Distributing apps)

[Jeff Hardy]

On Fri, Mar 2, 2012 at 9:14 AM, Slide <slide.o.mix at gmail.com> wrote:
> Do we currently have a wiki?

2 of them - codeplex, and github - plus ironpython.info has stuff as
well. For now the github wiki is probably the best one to use.

On a bigger scale:

I've long been in awe of the Python documentation. It's some of the
best I've ever seen. So I decided to just copy it :)

If you look at https://github.com/IronLanguages/ironpython-docs you
can get an idea; although I wanted to get it further along before
publicizing, now's as good a time as any to explain where I'm going
with this.

There's a site called readthedocs.org that is designed to host Sphinx
(the toolkit the Python docs use) documentation. You link a repository
to it and it pulls from it and builds the docs. One nice feature is
that it can automatically rebuild it when a push happens.

It just so happens that github has long supported editing files
through its web interface, which is slightly odd for code but perfect
for documentation.

So, what I see happening: someone wants to add to the documentation;
they go to github, edit the file, commit it, and RTD will
automatically update the docs. It's about the lowest possible friction
to getting nice docs. Admittedly, it's a lot like a wiki, but the
output of sphinx is much nicer and much more customizable then any
wiki we have available.

I plan to keep the basic structure of Python docs but replacing
sections like 'Extending & Embedding' with IronPython-specific stuff.
Of course, I won't be able to do it myself, but hopefully the simple
workflow will make it easier for others to contribute as well.

All of this setup will probably happen after 2.7.2 is released. but
that's what I had in mind.

- Jeff