Friday, March 20, 2009

Where to host docs?

I'm working on some preliminary sqlpython docs using Sphinx, which is really really nice. No guarantees that they will remain there, though - they need a home without a raw IP address for a URL!

I'm trying to figure out a permanent home for the docs. Here are the possibilities I know of.
  • Host the files on my own server. Buy a domain name (but not like last time). This is obviously the best option... unless I ever decide to quit paying for the domain, or the server, or forget to, or get hit by a bus. So really, I'd prefer something that wasn't so dependent on, well, me.
  • Sourceforge, Assembla, Google Code, and probably everybody else who hosts projects also let you create and host wiki-style documentation. As far as I know, though, there's no way to upload Sphinx documentation into any of them; the wiki form and the Sphinx form are not compatible.
  • Google Pages gives you free webpages with a reasonable URL - but no folders. Sphinx depends on a folder structure - it creates folders "html", "doctrees", "_sources", "_static", and maybe more once I get serious.
  • Creating a Google App Engine to host the docs - now this is an intriguing possibility. I'm going to check it out. Still, it would be nice if posting the docs for a technical project were not, itself, a technical project.
Any possibilities I'm missing? A convenient way to host Sphinx docs, freely available, would be a really nice service to FOSS developers. I wonder if the Google App Engine approach could be extended to provide that... hmm hmm hmm... just what I needed, one more project...

3 comments:

Xavier said...

Well, the easiest solution since you mentioned you already have your own server running, is to set up a dynamic DNS entry at one of the many dynamic DNS service providers like dyndns.com or easydns.com, etc... They'll give you a second-level DNS entry e.g. sqlpython.blogdns.com for free, you just point it to your IP and you're done.

If you have a dynamic IP address, install ddclient (http://ddclient.wiki.sourceforge.net/) and it will track your outside IP and update your account automatically to point it to the new one.

Also, Sourceforge isn't limited to their own doc system... you can use static HTML files as your project's website itself, so you can dump the docs in there for sure... set it up on sqlpython.sf.net and you're good to go.

I love the idea of a generic Google App Engine app for posting and managing docs, but since docs are just static html, it then turns App Engine into a free file hosting app, which might violate ToS.

Georg Brandl said...

If your code is hosted on PyPI, you get space for static documentation at http://packages.python.org/packagename. You can upload it in form of a zipfile at your PyPI admin page.

Luca Canali said...

Well done for sqlpyton 1.6.0! and the documentation written with Sphynx looks really nice. If you need I can also host the docs, but it will have to be a web space registered to my name (under the cern.ch domain) but I guess it will have the same problem as the first possibility you mentioned in your post.
Best regards,
Luca