Sphinx documentation inside a Flask running web application

Question

I\'ve locally built static Sphinx documentations (using make html).

I wish now to integrate the Sphinx files into my webapp that runs with Flask. From the

Answer 1

You could just handle it with your web server, the same way you handle the /static directory in Flask. For example if you used Apache as your production web server, you might add

Alias /documentation /location/of/sphinx/html
<Directory /location/of/sphinx/html>
    Order deny,allow
    Allow from all
</Directory>

to your Apache site configuration, so then you could just link directly to http://yoursite.com/documentation to access the Sphinx files, avoiding Flask altogether.

Answer 2

Other solutions nicely omit the Flask object initialization, which lead me to bang my head against the wall for a while.

Without touching the Sphinx project structure at all, here's the solution that worked for me:

from flask import Flask

app = Flask(__name__, static_url_path='/', static_folder='_build/html/')


@app.route('/')
@app.route('/<path:path>')
def serve_sphinx_docs(path='index.html'):
    return app.send_static_file(path)


if __name__ == '__main__':
    app.run(debug=True)

And below is the file structure of the project, where <doc> represents the rst files I actually wrote for the documentation, and app.py is the file containing the Flask app code above.

.
├── Makefile
├── _build
│   ├── doctrees
│   │   ├── index.doctree
│   │   ├── <doc>.doctree
│   │   ├── ...
│   │   └── <doc>.doctree
│   └── html
│       ├── _images
│       ├── _modules
│       │   ├── index.html
│       │   └── <package name>
│       │       └── ...
│       ├── _sources
│       │   ├── <doc>.rst.txt
│       │   ├── ...
│       │   └── <doc>.rst.txt
│       ├── _static
│       │   ├── ajax-loader.gif
│       │   ├── alabaster.css
│       │   └── ...
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── py-modindex.html
│       ├── search.html
│       ├── searchindex.js
│       ├── <doc>.html
│       ├── ...
│       └── <doc>.html
├── _static
│   ├── custom.css
│   └── <myimage>.gif
├── _templates
├── app.py
├── conf.py
├── index.rst
├── make.bat
├── <doc>.rst
├── ...
└── <doc>.rst

Answer 3

You can copy the _build/html folder from your docs to a doc folder in your flask static directory, and serve them with the following rule:

@app.route('/doc/<dir>/<filename>', defaults={'static': True})
def doc(dir='',filename='index.html'):
    path = join(dir,filename)
    return app.send_static_file(path)

Answer 4

In some cases you do not want to expose your docs to all users so configuring at the Apache or Nginx level is not an option. The following worked for me:

@app.route('/docs', defaults = {'filename': 'index.html'})
@app.route('/docs/<path:filename>')
@login_required
def web_docs(filename):
    path = os.path.join('docs/html', filename)
    return app.send_static_file(path)