Installing Sphinx on App Engine - possible?

Question

Following up on my last year's question on documentation, I now want to get started and try out Python-based Sphinx for putting together the developer documentation for a PHP CMS I've been working on.

Instead of setting up Python locally on my workstation, I would like to run it on a publicly accessible web server from the start. All the web hosting packages I have access to run on the LAMP stack, and I'm reluctant to buy Python-based hosting. I am very interested in the Google App Engine, the free quotas they provide will do for me a hundred times over, and even if not, their pricing looks very reasonable.

Now I have zero knowledge of Python - getting Sphinx to work would be my first contact with it - and very little time. As far as I understand, the platform and python libraries the App Engine provides are very compatible to a standard Python library but not identical.

So my question is:

• Can Sphinx run on App Engine at all?

• Is installing Sphinx on the App Engine as straightforward as if I would install it on top of a normal Python installation? Or will the App Engine's environment require tweaking of the source code that I can't perform in reasonable time with my current level of Python?

• Should I be installing Sphinx on a local server and a "normal" Python stack instead first?

• Does anybody know any helpful How-to's, tutorials or other resources for this?

Answer 1

Interesting project! The main issue you're going to run into is that of filesystem access: The filesystem on App Engine is read-only, and based on looking at the source, Sphinx is fairly hard-coded to use the filesystem for output. It also expects to read the configuration file and input files from the local filesystem, which would make building docs for anything other than projects bundled with the app tricky.

It is possible to work around this, but it would require writing a simple virtual filesystem that uses the App Engine datastore, and using monkeypatching to make it work with the regular Python file interface. That's rather advanced for a "new to Python" project!

One other thing you might want to consider if you were pondering allowing users to upload projects to be documented: The Sphinx configuration file is in Python, so executing it could be dangerous - a user could do nasty things to your app with a malicious configuration file!

Answer 2

You do not need to install Sphinx on GAE at all.

You use Sphinx to create a directory of static HTML, CSS and JS. When this step is finished, you simply upload the output from Sphinx -- in it's entirety.

The output from Sphinx (HTML, CSS and JS) is simply served from one place. You upload the documentation from where you created it to GAE as static files and serve them. Done.

There's no "install on a web server" aspect to Sphinx at all. Sphinx is not a web application; it does not run on your web server. You run it in development briefly to publish the documentation to HTML, LaTeX or whatever. Once you've created the static HTML files, you no longer need any part of Sphinx anywhere.

Can Sphinx run on App Engine at all?

I suppose it can, but you never need to.

Is installing Sphinx on the App Engine as straightforward as...

It doesn't matter, because you don't install it there. You install it on your workstation and use it on your workstation.

Should I be installing Sphinx on a local server and a "normal" Python stack instead first?

Don't install it on a server. Install it on your workstation.

Does anybody know any helpful How-to's, tutorials or other resources for this?

If by "this" you mean "installing on a web server", then then answer is "no". One does not install it on a web server. So there are no how-to's, tutorials or resources for "installing on a web server".

If by "this" you mean "creating documentation with Sphinx", then the answer is "what's wrong with http://sphinx.pocoo.org? What do they lack?

---

I would like Sphinx's "engine" that turns the input (consisting of reST files) into HTML/CSS/JS to be accessible from anywhere to make me (and possible other contributors) independent from a specific workstation.

Sphinx is like a compiler. Everyone has their own copy on their workstation. They download the document source, make changes, commit the source changes, and upload the resulting document.

serve the generated documentation from the same place.

Correct. After you download the source, make changes, regenerate the document and commit the changes, you upload the resulting document so it will be served from one -- and only one -- place.

Sphinx is a compiler. It is not a "web engine". It's a simple compiler that simply compiles your documentation into HTML so it can be served.

Answer 3

The difference between deployment locally via dev_appserver and remotely via appcfg has been - in my experience - limited to which of the two commands I execute. That said, I've no experience with Sphinx.

Answer 4

Sphinx compiles documentation, running it on a webserver makes as much sense as running gcc on a webserver.