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?
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 https://www.sphinx-doc.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.
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!
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.
Sphinx compiles documentation, running it on a webserver makes as much sense as running gcc on a webserver.
Related
Yesterday I have found information about G-WAN server.
I have searched many websites but I couldn't discover how to run frameworks like Web2Py which is more complex then simple hello.py file.
Is there an easy way to do this?
Maybe uWSGI support?
G-WAN supports the CGI interface, so the CGI environment variables are already there. Usually, Web frameworks are built over this layer.
If uWSGI provides more environment variables that are needed for your project then please drop us a line at gwan.com to explain more precisely what you need.
As a fledgling Django developer, I was wondering if it was customary, or indeed possible, to create a site with Django then transfer the complete file structure to a different machine where it would "go live".
Thanks,
~Caitlin
You could use GIT or Mercurial - or other version control system. To put the site structure on a central server. After that you could deploy the site for example with fabric to multiple servers. For deployment process you should consider using for example virtualenv to isolate the project from global python packages and requirements.
Of course that's possible and in fact it's the only way to "go live". You don't want to develop in your live server, do you? And it's true for any platform, not just django.
If I understood your question correctly, you need a system to push your development code to live.
Use a version control system: git, svn, mercurial etc.
Identify environment specific code like setting/config files etc. and have separate instances of them for each environment.
Create a testing/staging/PP environment which has live data or live-like data and deploy your code there before pushing it to live.
To avoid any downtime during deployment process, usually a symbolic link is created which points to the existing code folder. When a new release is to be pushed, a new folder is created with new code, after all other dependencies are done (like setting and database changes) and the sym link is pointed to the new folder.
I'm using several third party flask-extensions (flask-login, flask-security, flask-principal, flask-mongoengine etc...the list is about 12 deep) in an application that is failing silently in production environment (currently AppFog Paas)
I'm specifically trying to debug an issue with flask-security (I "think", but it could just as easily be flask-login, flask-mongoengine or any plugin in my authentication pipeline) since it has to do with logging in and redirecting the user to through the application.
I notice several things about flask extensions that's making them a big quirky/difficult to work with:
most don't have any debug logging in them
some have partial support for configuring (like using your own templates)
they install into the environment (I'm using virtualenv) as opposed to an application "plugins/extensions" directory
I'm wondering if there's some guidance around:
installing plugins into the project, so they can be quickly
modified (maybe logging added) and then pushed into production
without having to fork a github project and repackage it.
Standard logging practices for 3rd party extensions, or anything
that would help trace the code
Any information/tips to help me debug my current problems
Thanks.
I'm going to just answer my own question and say the best/easiest thing to do is just pull the extensions code into my project and modify as I need it.
Seems like this will be the case with several Flask-extensions that involve more view/template code than pure infrastructure (like flask-security/flask-login, etc.)
I am doing some research on taking a python app written in either django or web2py, and using it as a desktop app. And for a database, remotely I will be using couchdb for it's replication abilities. For the dektop, I need to find a way to integrate pouchdb into the app, but short of the homepage saying to include the pouchdb.js file, I can't find any docs on how to use it with python. And how to get setup in general for localhost to remote server syncing.
I was hoping someone could shed some light on how to get this accomplished. As for django/web2py, im not sure which one I want to use yet but have narrowed it down to those 2.
The idea for the app itself is that I have the website which has all the normal functionality available. And the user can install a package locally to their desktop from an installer. That local copy would have a subset of features from the website and sync some data from the pouchdb instance locally, to the remote server. enough to be able to fully interact with the db when offline.
For this purpose I created Python-PouchDB a few days ago. It runs PouchDB inside QtWebKit via either PyQt4, PyQt5 or PySide (you need to ship one of them with your app), and provides a nice (both synchronous and asynchronous) Python interface.
You can install it by executing:
pip install python-pouchdb
(or just by extracting the pouchdb directory from the source which you can find linked on the website.)
Example usage:
>>> import pouchdb
>>> environment = pouchdb.setup()
>>> db = environment.PouchDB("test")
>>> db.put({"_id": "mytest"})
{u'ok': True, u'rev': u'...', u'id': u'mytest'}
>>> db["mytest"] #shorthand for db.get()
{u'_rev': u'...', u'_id': u'mytest'}
>>> db.destroy()
PouchDB runs on IndexedDB in the browser, with future plans for supporting WebSQL, but in general the idea is the it builds on local database capabilities provided by the browser.
If I understood right you want to be able to access it from Python? I don't think that's going to be possible, while finding a Python wrapper around a JavaScript engine might be possible, but you wouldn't be able to access the browser backed database.
You should also consider making a CouchApp instead, though that still won't give you the ability to use Django templates.
Basically the way you should structure your app is that it only uses JavaScript based templating (Mustache, Handlebars, etc etc) and interact with your API using a REST interface, so you don't have to have a Python engine running for the client side offline app. It might still be doable, but if you have to bundle tons of technologies with your app it will be a heavy download.
For very simple, internal web-apps using ASP I was able to just switch IIS 'on' and then write some ASP scripts in the www directory that would start working immediately.
Is there an equivalent webserver app for Python scripts that I can run that will automatically start serving dynamic pages (python scripts) in a certain folder (with virtually no configuration)?
Solutions I've already found are either too limited (e.g. SimpleHTTPRequestHandler doesn't serve dynamic content) or require configuring the script that does the serving.
There's always CGI. Add a script mapping of .py to "C:\Python27\python.exe" -u "%s" then drop .py files in a folder and IIS will execute them.
I'd not generally recommend it for real work—in the longer term you would definitely want to write apps to WSGI, and then deploy them through any number of interfaces including CGI—but it can be handy for quick prototyping.
For development or just to play around, here's an example using the standard Python library that I have used to help friend who wanted to get a basic CGI server up and running. It will serve python scripts from cgi-bin and files from the root folder. I'm not near a Windows computer at the moment to make sure that this still works. This also assumes Python2.x. Python 3.x has this, it's just not named the same.
Make a directory on your harddrive with a cgi-bin folder in it (Ex. "C:\server\cgi-bin")
In a command window, navigate to "C:\server" directory
Type the following assuming you've installed python 2.7 in C:\Python27:
"c:\python27\python.exe -m CGIHTTPServer"
You should get a message like "Serving HTTP on 0.0.0.0 port 8000"
Linux is the same - "python -m CGIHTTPServer" in a directory with a cgi-bin/ in it.
WSGI setups are fairly easy to get started, but in no anyway turn key. django MVC has a simple built in development server if you plan on using a more comprehensive framework.
My limited experience with Python web frameworks has taught me that most go to one extreme or the other: Django on one end is a full-stack MVC framework, that will do pretty much everything for you. On the other end, there are Flask, web.py, CherryPy, etc., which do much less, but stay out of your way.
CherryPy, for example, not only comes with no ORM, and doesn't require MVC, but it doesn't even have a templating engine. So unless you use it with something like Cheetah, you can't write what would look like .asp at all.