[Ironpython-users] Codeplex says "No Documentation"

[Jeff Hardy]

Here's what my thinking has been on documentation for the past little
while. I just haven't had a chance to put it all together.

First off, there's a great site called readthedocs.org (RTD) that
hosts softwsre documentation (for free). I believe it works with any
sort of documentation if you set it up right, but it's designed for
Sphinx (http://sphinx.pocoo.org/) documentation. Sphinx, as it
happens, was originally written to manage Python's documentation, so
all of the existing Python documentation is written for Sphinx and
thus works quite nicely with RTD.

RTD also has a handy feature where you can have it pull from a git
repo, and GitHub has a hook that will tell RTD when your documentation
has changed. GitHub also supports editing files directly from its
website, and supports merging changes directly from the website as
well.

OK, enough meandering background. :) My idea was that we would take a
copy of the Python documentation, store in a git repo (say,
https://github.com/IronLanguages/ironpython-docs), and make any
IronPython-specific changes there, such as notes on the standard
library (what IronPython does/doesn't support, etc.) and IP-specific
documentation on creating modules, embedding IronPython, and
interoperating with .NET code. When the repo's master is updated the
docs will automatically get rebuilt and pushed live. GitHub even
provides a 'fork-and-edit' operation that we can link to - click it,
edit the page, submit a pull request, merge online, new docs show up
~1 hour later.

Like a wiki, it can be edited online, merge requests can be handled
online, everything - and pretty docs will automatically get built. RTD
also supports CNAMEs, so the docs would eventually live at
docs.ironpython.net.

You can see what they might look like at
http://readthedocs.org/docs/ironpython-test/en/latest/index.html.

I'd be very glad to get some help with this if it makes sense to you,
Vernon. It offers a lot of advantages over the Codeplex wiki, and none
of the downsides as far as I can see.

- Jeff

On Sun, Apr 29, 2012 at 11:57 AM, Vernon Cole <vernondcole at gmail.com> wrote:
> I noticed today that IronPython's codeplex page has an empty "Documentation"
> tab.  It just says: "There is no documentation yet."  I wish to fix that
> problem.
>
> Is http://ironpython.net/documentation/ actually our official
> documentation?  If so, the site needs some updating. Who can do that?
>
> Or is it https://github.com/IronLanguages/ironpython-docs ? If so, user
> access needs to be a bit more friendly.
>
> Or did I miss something entirely that everyone else already knows?
>
> I am an editor on the codeplex project page. I will make appropriate updates
> based on the consensus of replies to this message.
> --
> Vernon Cole
>
>
>
> _______________________________________________
> Ironpython-users mailing list
> Ironpython-users at python.org
> http://mail.python.org/mailman/listinfo/ironpython-users
>