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 <vernondc...@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@python.org > http://mail.python.org/mailman/listinfo/ironpython-users > _______________________________________________ Ironpython-users mailing list Ironpython-users@python.org http://mail.python.org/mailman/listinfo/ironpython-users
