Upload docs to pythonhosted / pypi

[jgoppert]

Pypi now has a place to host docs for python packages. It would be good to upload our docs there.

You can now host documentation at http://pythonhosted.org/control. To upload documentation, prepare a .zip file that is unpacked into this URL. Only static pages are supported. The zip file must have a top-level "index.html".

[murrayrm]

There is also a current copy of the docs on SourceForge: http://python-control.sf.net/manual. Should we shift to PyPI or leave in both places?

[cwrowley]

No preference here. But I also wanted to point out that there is also a page on Richard's wiki (http://www.cds.caltech.edu/~murray/wiki/Control_Systems_Library_for_Python) with some out-of-date information, such as "Announcements: The python-control user documentation has been shifted from SourceForge to MurrayWiki at Caltech." This page is actually Google's first hit if you do "python control" (at least for me). Anyway, whatever we decide, it would be good to make this point to the most up-to-date user documentation.

[murrayrm]

Shifting the discussion about the (outdated) wiki page to issue #34, since it is a bit separate from where we should put the documentation (this issue).

[cwrowley]

Just to throw out another idea, another option would be to host the docs on readthedocs.org. I just tried this out and it looks pretty nice: http://python-control.readthedocs.org/. It was trivial to setup and build the docs, although for now I just did this with my own fork of the main repo. If we want to make this the "real" place for the docs, it's probably best for me to delete this site and for Richard to set up the official one.

I think readthedocs looks more polished than the "standard" Sphinx theme (e.g. the current docs), and I think the table-of-contents navigation bar at the left of the page is much nicer than the standard sphinx navigation stuff. Also note that on the readthedocs site, if you click the dark rectangle at the bottom of the navigation bar, you can do other things, like download a pdf version, etc. This all seems pretty slick to me.

But I don't know: is pythonhosted more standard for Python packages? Not sure.

Any thoughts on pythonhosted vs. readthedocs?

[slivingston]

I want to rekindle this issue and argue for using readthedocs.org. Besides the motivation that @cwrowley gave above, two other important features for us are

• alternate domain names may be used; e.g., www.python-control.org could point there.
• multiple versions may be hosted.

The second item is motivated by there being people who are using distinct versions of control.

[cwrowley]

I'd still be in favor of moving the documentation to readthedocs.org too. It seems very easy to keep up-to-date, and I agree that the multiple-version feature could be useful. I had set up an example at the link above, that points to a fork I'd made of the main repository, but Richard, I am happy to remove that and let you set up the "real" thing under your name, or just set up mine to point to the main repository.

[murrayrm]

I like the features of readthedocs.org! Seems like a good way to go.

@cwrowley, can you set things up so that this works going forward? I don't see any reason to put the "real" thing under my name versus anyone else's. Can we put up the documentation for 0.6d (the currently official release) and then 0.6.5 (current master)?

[cwrowley]

Yes, happy to do this. There are a couple of small changes needed to make the documentation build properly, so I will add these to the main repo (in a new branch) and then submit a pull request. I'll add the branch from v0.6d and then we can merge it in with master too, so we can maintain both versions of the documentation on readthedocs.org.

[cwrowley]

Version 0.7.0 is now available at http://python-control.readthedocs.org