Intro¶

Here is a solution described as Sphinx how to reach a multi-language documentation service.

Why Sphinx?¶

Sphinx is used to document Python. Documentation strings from Python modules are fetched and Sphinx will generate documentation from that.

Output¶

For the output there are different Builders. You can choose between single- or multi-page HTML, TXT, PDF, or ePub. There are also other output formats like JSON, XML, or man-pages. With hieroglyph you can also generate slides. The builder will also make syntax- and link checks for the documents.

Input¶

The documents are written in restructuredtext

The syntax is pretty easy, i.e. print tables. Or print code:

# python -m sphinx.ext.intersphinx 'http://www.sphinx-doc.org/en/master/objects.inv

Or download the document.

Markdown is also supported as source.

Templating¶

Other things in Sphinx are templating. Default template engine is Jinja. You can use variables in loops to work with data from json files or others.

Themes¶

Last but not least to highlight are Themes. There are some themes included in Sphinx and the standard theme has multiple options to configure. But you can also build yuur own theme, or look what Python Packages are available for Sphinx Theme

Search Engine¶

A search engine is included.

Not enough?¶

And mark a timestamp without and script language

Apr 08, 2018

And who is using Sphinx?¶

others:

Projects using Sphinx
=====================

This is an (incomplete) alphabetic list of projects that use Sphinx or
are experimenting with using it for their documentation.  If you like to
be included, please mail to `the Google group
`_.

I've grouped the list into sections to make it easier to find
interesting examples.

Documentation using the alabaster theme
---------------------------------------

* Alabaster: https://alabaster.readthedocs.io/
* Blinker: https://pythonhosted.org/blinker/
* Calibre: https://manual.calibre-ebook.com/
* Click: http://click.pocoo.org/ (customized)
* coala: https://docs.coala.io/ (customized)
* CodePy: https://documen.tician.de/codepy/
* Fabric: http://docs.fabfile.org/
* Fityk: http://fityk.nieto.pl/
* Flask: http://flask.pocoo.org/docs/
* Flask-OpenID: https://pythonhosted.org/Flask-OpenID/
* Invoke: http://docs.pyinvoke.org/
* Jinja: http://jinja.pocoo.org/docs/
* Lino: http://www.lino-framework.org/ (customized)
* marbl: https://getmarbl.readthedocs.io/
* MDAnalysis: http://www.mdanalysis.org/docs/ (customized)
* MeshPy: https://documen.tician.de/meshpy/
* PyCUDA: https://documen.tician.de/pycuda/
* PyOpenCL: https://documen.tician.de/pyopencl/
* PyLangAcq: http://pylangacq.org/
* pytest: https://docs.pytest.org/ (customized)
* python-apt: https://apt.alioth.debian.org/python-apt-doc/
* PyVisfile: https://documen.tician.de/pyvisfile/
* Requests: http://www.python-requests.org/
* searx: https://asciimoo.github.io/searx/
* Tablib: http://docs.python-tablib.org/
* urllib3: https://urllib3.readthedocs.io/ (customized)
* Werkzeug: http://werkzeug.pocoo.org/docs/ (customized)

Documentation using the classic theme
-------------------------------------

* Advanced Generic Widgets: http://xoomer.virgilio.it/infinity77/AGW_Docs/ (customized)
* Apache CouchDB: http://docs.couchdb.org/ (customized)
* APSW: https://rogerbinns.github.io/apsw/
* Arb: http://arblib.org/
* Bazaar: http://doc.bazaar.canonical.com/ (customized)
* Beautiful Soup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
* Blender: https://docs.blender.org/api/current/
* Bugzilla: https://bugzilla.readthedocs.io/
* Buildbot: https://docs.buildbot.net/latest/
* CMake: https://cmake.org/documentation/ (customized)
* Chaco: http://docs.enthought.com/chaco/ (customized)
* Cormoran: http://cormoran.nhopkg.org/docs/
* DEAP: https://deap.readthedocs.io/ (customized)
* Director: https://pythonhosted.org/director/
* EZ-Draw: https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html (customized)
* F2py: http://f2py.sourceforge.net/docs/
* Generic Mapping Tools (GMT): http://gmt.soest.hawaii.edu/doc/latest/ (customized)
* Genomedata: https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/
* GetFEM++: http://getfem.org/ (customized)
* Glasgow Haskell Compiler: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ (customized)
* Grok: http://grok.zope.org/doc/current/ (customized)
* GROMACS: http://manual.gromacs.org/documentation/
* GSL Shell: http://www.nongnu.org/gsl-shell/
* Hands-on Python Tutorial: http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
* Kaa: http://api.freevo.org/kaa-base/ (customized)
* Leo: http://leoeditor.com/
* LEPL: http://www.acooke.org/lepl/ (customized)
* Mayavi: http://docs.enthought.com/mayavi/mayavi/ (customized)
* MediaGoblin: https://mediagoblin.readthedocs.io/ (customized)
* mpmath: http://mpmath.org/doc/current/
* OpenCV: http://docs.opencv.org/ (customized)
* OpenEXR: http://excamera.com/articles/26/doc/index.html
* OpenGDA: http://www.opengda.org/gdadoc/html/
* Peach^3: https://peach3.nl/doc/latest/userdoc/ (customized)
* Plone: https://docs.plone.org/ (customized)
* PyEMD: https://pyemd.readthedocs.io/
* Pyevolve: http://pyevolve.sourceforge.net/
* Pygame: https://www.pygame.org/docs/ (customized)
* PyMQI: https://pythonhosted.org/pymqi/
* PyQt4: http://pyqt.sourceforge.net/Docs/PyQt4/ (customized)
* PyQt5: http://pyqt.sourceforge.net/Docs/PyQt5/ (customized)
* Python 2: https://docs.python.org/2/
* Python 3: https://docs.python.org/3/ (customized)
* Python Packaging Authority: https://www.pypa.io/ (customized)
* Ring programming language: http://ring-lang.sourceforge.net/doc/ (customized)
* SageMath: https://doc.sagemath.org/ (customized)
* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
* simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html (customized)
* Sprox: http://sprox.org/ (customized)
* SymPy: http://docs.sympy.org/
* TurboGears: https://turbogears.readthedocs.io/ (customized)
* tvtk: http://docs.enthought.com/mayavi/tvtk/
* Varnish: https://www.varnish-cache.org/docs/ (customized, alabaster for index)
* Waf: https://waf.io/apidocs/
* wxPython Phoenix: https://wxpython.org/Phoenix/docs/html/main.html (customized)
* z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
* zc.async: https://pythonhosted.org/zc.async/ (customized)
* Zope: https://docs.zope.org/zope2/ (customized)

Documentation using the sphinxdoc theme
---------------------------------------

* cartopy: http://scitools.org.uk/cartopy/docs/latest/
* Jython: http://www.jython.org/docs/
* Matplotlib: https://matplotlib.org/
* MDAnalysis Tutorial: http://www.mdanalysis.org/MDAnalysisTutorial/
* NetworkX: https://networkx.github.io/
* PyCantonese: http://pycantonese.org/
* Pyre: http://docs.danse.us/pyre/sphinx/
* pySPACE: https://pyspace.github.io/pyspace/
* Pysparse: http://pysparse.sourceforge.net/
* PyTango:
  http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/
* Python Wild Magic: https://vmlaker.github.io/pythonwildmagic/ (customized)
* Reteisi: http://www.reteisi.org/contents.html (customized)
* Sqlkit: http://sqlkit.argolinux.org/ (customized)
* Turbulenz: http://docs.turbulenz.com/

Documentation using the nature theme
------------------------------------

* Alembic: http://alembic.zzzcomputing.com/
* Cython: http://docs.cython.org/
* easybuild: https://easybuild.readthedocs.io/
* jsFiddle: http://doc.jsfiddle.net/
* libLAS: https://www.liblas.org/ (customized)
* Lmod: https://lmod.readthedocs.io/
* MapServer: http://mapserver.org/ (customized)
* Pandas: https://pandas.pydata.org/pandas-docs/stable/
* pyglet: https://pyglet.readthedocs.io/ (customized)
* Setuptools: https://setuptools.readthedocs.io/
* Spring Python: https://docs.spring.io/spring-python/1.2.x/sphinx/html/
* StatsModels: http://www.statsmodels.org/ (customized)
* Sylli: http://sylli.sourceforge.net/

Documentation using another builtin theme
-----------------------------------------

* Breathe: https://breathe.readthedocs.io/ (haiku)
* MPipe: https://vmlaker.github.io/mpipe/ (sphinx13)
* NLTK: http://www.nltk.org/ (agogo)
* Programmieren mit PyGTK und Glade (German):
  http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo, customized)
* PyPubSub: https://pypubsub.readthedocs.io/ (bizstyle)
* Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/ (pyramid)
* Pyramid web framework:
  https://docs.pylonsproject.org/projects/pyramid/ (pyramid)
* Sphinx: http://www.sphinx-doc.org/ (sphinx13) :-)
* Valence: http://docs.valence.desire2learn.com/ (haiku, customized)

Documentation using sphinx_rtd_theme
------------------------------------

* Annotator: http://docs.annotatorjs.org/
* Ansible: https://docs.ansible.com/ (customized)
* Arcade: http://arcade.academy/
* aria2: https://aria2.github.io/manual/en/html/
* ASE: https://wiki.fysik.dtu.dk/ase/
* Autofac: http://docs.autofac.org/
* BigchainDB: https://docs.bigchaindb.com/
* Blocks: https://blocks.readthedocs.io/
* bootstrap-datepicker: https://bootstrap-datepicker.readthedocs.io/
* Certbot: https://letsencrypt.readthedocs.io/
* Chainer: https://docs.chainer.org/ (customized)
* CherryPy: http://docs.cherrypy.org/
* Chainer: https://docs.chainer.org/
* CodeIgniter: https://www.codeigniter.com/user_guide/
* Conda: https://conda.io/docs/
* Corda: https://docs.corda.net/
* Dask: https://dask.pydata.org/
* Databricks: https://docs.databricks.com/ (customized)
* Dataiku DSS: https://doc.dataiku.com/
* edX: http://docs.edx.org/
* Electrum: http://docs.electrum.org/
* Elemental: http://libelemental.org/documentation/dev/
* ESWP3: https://eswp3.readthedocs.io/
* Ethereum Homestead: http://www.ethdocs.org/
* Fidimag: https://fidimag.readthedocs.io/
* Flake8: http://flake8.pycqa.org/
* GeoNode: http://docs.geonode.org/
* Godot: https://godot.readthedocs.io/
* Graylog: http://docs.graylog.org/
* GPAW: https://wiki.fysik.dtu.dk/gpaw/ (customized)
* HDF5 for Python (h5py): http://docs.h5py.org/
* Hyperledger Fabric: https://hyperledger-fabric.readthedocs.io/
* Hyperledger Sawtooth: https://intelledger.github.io/
* IdentityServer: http://docs.identityserver.io/
* Idris: http://docs.idris-lang.org/
* javasphinx: https://bronto-javasphinx.readthedocs.io/
* Julia: https://julia.readthedocs.io/
* Jupyter Notebook: https://jupyter-notebook.readthedocs.io/
* Lasagne: https://lasagne.readthedocs.io/
* Linguistica: https://linguistica-uchicago.github.io/lxa5/
* Linux kernel: https://www.kernel.org/doc/html/latest/index.html
* MathJax: https://docs.mathjax.org/
* MDTraj: http://mdtraj.org/latest/ (customized)
* MICrobial Community Analysis (micca): http://micca.org/docs/latest/
* MicroPython: https://docs.micropython.org/
* Minds: https://www.minds.org/docs/ (customized)
* Mink: http://mink.behat.org/
* Mockery: http://docs.mockery.io/
* mod_wsgi: https://modwsgi.readthedocs.io/
* MoinMoin: https://moin-20.readthedocs.io/
* Mopidy: https://docs.mopidy.com/
* MyHDL: http://docs.myhdl.org/
* Nextflow: https://www.nextflow.io/docs/latest/index.html
* NICOS: https://forge.frm2.tum.de/nicos/doc/nicos-master/ (customized)
* Pelican: http://docs.getpelican.com/
* picamera: https://picamera.readthedocs.io/
* Pillow: https://pillow.readthedocs.io/
* pip: https://pip.pypa.io/
* Paver: https://paver.readthedocs.io/
* peewee: http://docs.peewee-orm.com/
* Phinx: http://docs.phinx.org/
* phpMyAdmin: https://docs.phpmyadmin.net/
* Pweave: http://mpastell.com/pweave/
* PyPy: http://doc.pypy.org/
* python-sqlparse: https://sqlparse.readthedocs.io/
* PyVISA: https://pyvisa.readthedocs.io/
* Read The Docs: https://docs.readthedocs.io/
* Free your information from their silos (French):
  http://redaction-technique.org/ (customized)
* Releases Sphinx extension: https://releases.readthedocs.io/
* Qtile: http://docs.qtile.org/
* Quex: http://quex.sourceforge.net/doc/html/main.html
* Satchmo: http://docs.satchmoproject.com/
* Scapy: https://scapy.readthedocs.io/
* SimPy: http://simpy.readthedocs.io/
* SlamData: http://docs.slamdata.com/
* Solidity: https://solidity.readthedocs.io/
* Sonos Controller (SoCo): http://docs.python-soco.com/
* Sphinx AutoAPI: https://sphinx-autoapi.readthedocs.io/
* sphinx-argparse: https://sphinx-argparse.readthedocs.io/
* Sphinx-Gallery: https://sphinx-gallery.readthedocs.io/ (customized)
* StarUML: http://docs.staruml.io/
* Sublime Text Unofficial Documentation: http://docs.sublimetext.info/
* SunPy: http://docs.sunpy.org/
* Sylius: http://docs.sylius.org/
* Tango Controls: https://tango-controls.readthedocs.io/ (customized)
* Topshelf: http://docs.topshelf-project.com/
* Theano: http://www.deeplearning.net/software/theano/
* ThreatConnect: https://docs.threatconnect.com/
* Tuleap: https://tuleap.net/doc/en/
* TYPO3: https://docs.typo3.org/ (customized)
* uWSGI: https://uwsgi-docs.readthedocs.io/
* Wagtail: http://docs.wagtail.io/
* Web Application Attack and Audit Framework (w3af): http://docs.w3af.org/
* Weblate: https://docs.weblate.org/
* x265: https://x265.readthedocs.io/
* ZeroNet: https://zeronet.readthedocs.io/

Documentation using sphinx_bootstrap_theme
------------------------------------------

* Bootstrap Theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme/
* C/C++ Software Development with Eclipse: http://eclipsebook.in/
* Dataverse: http://guides.dataverse.org/
* e-cidadania: https://e-cidadania.readthedocs.io/
* Hangfire: http://docs.hangfire.io/
* Hedge: https://documen.tician.de/hedge/
* ObsPy: https://docs.obspy.org/
* Open Dylan: https://opendylan.org/documentation/
* Pootle: http://docs.translatehouse.org/projects/pootle/
* PyUblas: https://documen.tician.de/pyublas/
* seaborn: https://seaborn.pydata.org/

Documentation using a custom theme or integrated in a website
-------------------------------------------------------------

* Apache Cassandra: https://cassandra.apache.org/doc/
* Astropy: http://docs.astropy.org/
* Bokeh: https://bokeh.pydata.org/
* Boto 3: https://boto3.readthedocs.io/
* CakePHP: https://book.cakephp.org/
* CasperJS: http://docs.casperjs.org/
* Ceph: http://docs.ceph.com/docs/master/
* Chef: https://docs.chef.io/
* CKAN: http://docs.ckan.org/
* Confluent Platform: http://docs.confluent.io/
* Django: https://docs.djangoproject.com/
* Doctrine: http://docs.doctrine-project.org/
* Enterprise Toolkit for Acrobat products:
  https://www.adobe.com/devnet-docs/acrobatetk/
* Gameduino: http://excamera.com/sphinx/gameduino/
* gensim: https://radimrehurek.com/gensim/
* GeoServer: http://docs.geoserver.org/
* gevent: http://www.gevent.org/
* GHC - Glasgow Haskell Compiler: http://downloads.haskell.org/~ghc/master/users-guide/
* Guzzle: http://docs.guzzlephp.org/en/stable/
* H2O.ai: http://docs.h2o.ai/
* Istihza (Turkish Python documentation project): https://belgeler.yazbel.com/python-istihza/
* Kombu: http://docs.kombu.me/
* Lasso: http://lassoguide.com/
* Mako: http://docs.makotemplates.org/
* MirrorBrain: http://mirrorbrain.org/docs/
* MongoDB: https://docs.mongodb.com/
* Music21: http://web.mit.edu/music21/doc/
* MyHDL: http://docs.myhdl.org/en/latest/
* nose: https://nose.readthedocs.io/
* ns-3: https://www.nsnam.org/documentation/
* NumPy: https://docs.scipy.org/doc/numpy/reference/
* ObjectListView: http://objectlistview.sourceforge.net/python/
* OpenERP: https://doc.odoo.com/
* OpenCV: http://docs.opencv.org/
* OpenLayers: http://docs.openlayers.org/
* OpenTURNS: http://openturns.github.io/openturns/master/
* Open vSwitch: http://docs.openvswitch.org/
* PlatformIO: http://docs.platformio.org/
* PyEphem: http://rhodesmill.org/pyephem/
* Pygments: http://pygments.org/docs/
* Plone User Manual (German): https://www.hasecke.com/plone-benutzerhandbuch/4.0/
* PSI4: http://www.psicode.org/psi4manual/master/index.html
* PyMOTW: https://pymotw.com/2/
* python-aspectlib: https://python-aspectlib.readthedocs.io/
  (`sphinx_py3doc_enhanced_theme `__)
* QGIS: https://qgis.org/en/docs/index.html
* qooxdoo: http://www.qooxdoo.org/current/
* Roundup: http://www.roundup-tracker.org/
* SaltStack: https://docs.saltstack.com/
* scikit-learn: http://scikit-learn.org/stable/
* SciPy: https://docs.scipy.org/doc/scipy/refrence/
* Scrapy: https://doc.scrapy.org/
* Seaborn: https://seaborn.pydata.org/
* Selenium: http://docs.seleniumhq.org/docs/
* Self: http://www.selflanguage.org/
* Substance D: https://docs.pylonsproject.org/projects/substanced/
* Sulu: http://docs.sulu.io/
* SQLAlchemy: https://docs.sqlalchemy.org/
* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
* Twisted: http://twistedmatrix.com/documents/current/
* Ubuntu Packaging Guide: http://packaging.ubuntu.com/html/
* WebFaction: https://docs.webfaction.com/
* WTForms: https://wtforms.readthedocs.io/

Homepages and other non-documentation sites
-------------------------------------------

* Arizona State University PHY494/PHY598/CHM598 Simulation approaches to Bio-
  and Nanophysics:
  https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/ (classic)
* Benoit Boissinot: https://bboissin.appspot.com/ (classic, customized)
* Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab):
  https://lab.miletic.net/ (sphinx_rtd_theme)
* Deep Learning Tutorials: http://www.deeplearning.net/tutorial/ (sphinxdoc)
* Loyola University Chicago COMP 339-439 Distributed Systems course:
  http://books.cs.luc.edu/distributedsystems/ (sphinx_bootstrap_theme)
* Pylearn2: http://www.deeplearning.net/software/pylearn2/ (sphinxdoc, customized)
* SciPy Cookbook: https://scipy-cookbook.readthedocs.io/ (sphinx_rtd_theme)
* The Wine Cellar Book: https://www.thewinecellarbook.com/doc/en/ (sphinxdoc)
* Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials:
  http://thomas-cokelaer.info/tutorials/ (standard)
* UC Berkeley ME233 Advanced Control Systems II course:
  https://berkeley-me233.github.io/ (sphinxdoc)

Books produced using Sphinx
---------------------------

* "Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski":
  https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/
* "Expert Python Programming":
  https://www.packtpub.com/application-development/expert-python-programming
* "Expert Python Programming" (Japanese translation):
  https://www.amazon.co.jp/dp/4048686291/
* "The Hitchhiker's Guide to Python": http://docs.python-guide.org/en/latest/
* "LassoGuide": http://www.lassosoft.com/Lasso-Documentation
* "Learning Sphinx" (in Japanese):
  https://www.oreilly.co.jp/books/9784873116488/
* "Mercurial: the definitive guide (Second edition)":
  https://book.mercurial-scm.org/
* "Pioneers and Prominent Men of Utah": http://pioneers.rstebbing.com/
* "Pomodoro Technique Illustrated" (Japanese translation):
  https://www.amazon.co.jp/dp/4048689525/
* "Python Professional Programming" (in Japanese):
  http://www.amazon.co.jp/dp/4798032948/
* "The ``repoze.bfg`` Web Application Framework":
  https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
* "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
  https://www.amazon.co.jp/dp/477414259X/
* "Software-Dokumentation mit Sphinx": https://www.amazon.de/dp/1497448689/
* "Theoretical Physics Reference": http://www.theoretical-physics.net/
* "The Varnish Book":
  https://info.varnish-software.com/the-varnish-book

Theses produced using Sphinx
----------------------------

* "A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use
  of CouchDB":
  https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042
* "Content Conditioning and Distribution for Dynamic Virtual Worlds":
  https://www.cs.princeton.edu/research/techreps/TR-941-12
* "The Sphinx Thesis Resource": https://jterrace.github.io/sphinxtr/

Intro¶

Why Sphinx?¶

Output¶

Input¶

Templating¶

Themes¶

Search Engine¶

Not enough?¶

And who is using Sphinx?¶

Table Of Contents

Previous topic

Next topic

This Page