Sphinx 快速入门

Sphinx 简介

Sphinx 令人可以轻松撰写出专业、优雅的文档, 由Georg Brandl在BSD许可证下创造。

Sphinx 采用reStructureText-新结构化文本格式编写文档，可以同时支持HTML、Markdown等流行的格式，并且通过nbsphinx插件可以支持Jupyter Notebook的.ipynb格式。Sphinx支持文档目录自动创建、搜索等功能，可以输出HTMl、PDF等多种格式，还可以通过Github来协同编写版本化的文档，然后在ReadTheDocs.org在线共享生成的文档，或者通过ReadTheDoc开源服务端软件来搭建自己的文档系统。

Sphinx 特性

Python的文档采用Sphinx创建和管理，已支持最新版Python的文档生成, 已经成为Python相关项目的首选文档工具，同时也对C/C++以及其它语言的工程有较好的支持。

Sphnix具有下列特性，并已在Python官方文档中体现:

• 丰富的输出格式: HTML (包括M$帮助), LaTeX (为PDF输出), manual pages(man), 纯文本
• 完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
• 明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
• 美观的自动索引: 可自动生成美观的模块索引
• 精确的语法高亮: 基于 Pygments 自动生成语法高亮
• 开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等。

Sphinx 文档

Sphinx中文版是改进的中文版，使用了Sphinx-rtd-theme更易于阅读，增加了中文字符集的支持和PDF输出选项。可以在这里查看以前版本，需要注意其中的变更，可能新版本的Sphinx中已经不再适用。

Sphinx 项目

大量的软件项目使用了Sphinx文档系统，下面是其中一些比较有影响的项目。

缺省theme

• APSW: http://apidoc.apsw.googlecode.com/hg/index.html
• ASE: https://wiki.fysik.dtu.dk/ase/
• boostmpi: http://documen.tician.de/boostmpi/
• Calibre: http://calibre-ebook.com/user_manual/
• CodePy: http://documen.tician.de/codepy/
• Cython: http://docs.cython.org/
• C++ Python language binding project: http://language-binding.net/index.html
• Cormoran: http://cormoran.nhopkg.org/docs/
• Director: http://packages.python.org/director/
• Dirigible: http://www.projectdirigible.com/documentation/
• Elemental: http://elemental.googlecode.com/hg/doc/build/html/index.html
• F2py: http://f2py.sourceforge.net/docs/
• GeoDjango: http://geodjango.org/docs/
• Genomedata: http://noble.gs.washington.edu/proj/genomedata/doc/1.2.2/genomedata.html
• gevent: http://www.gevent.org/
• Google Wave API: http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
• GSL Shell: http://www.nongnu.org/gsl-shell/
• Heapkeeper: http://heapkeeper.org/
• Hands-on Python Tutorial: http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
• Hedge: http://documen.tician.de/hedge/
• Kaa: http://doc.freevo.org/api/kaa/
• Leo: http://webpages.charter.net/edreamleo/front.html
• Lino: http://lino.saffre-rumma.net/
• MeshPy: http://documen.tician.de/meshpy/
• mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
• OpenEXR: http://excamera.com/articles/26/doc/index.html
• OpenGDA: http://www.opengda.org/gdadoc/html/
• openWNS: http://docs.openwns.org/
• Paste: http://pythonpaste.org/script/
• Paver: http://paver.github.com/paver/
• Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
• PyCuda: http://documen.tician.de/pycuda/
• Pyevolve: http://pyevolve.sourceforge.net/
• Pylo: http://documen.tician.de/pylo/
• PyMQI: http://packages.python.org/pymqi/
• PyPubSub: http://pubsub.sourceforge.net/
• pyrticle: http://documen.tician.de/pyrticle/
• Python: http://docs.python.org/
• python-apt: http://apt.alioth.debian.org/python-apt-doc/
• PyUblas: http://documen.tician.de/pyublas/
• Quex: http://quex.sourceforge.net/doc/html/main.html
• Scapy: http://www.secdev.org/projects/scapy/doc/
• Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
• SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
• SymPy: http://docs.sympy.org/
• WTForms: http://wtforms.simplecodes.com/docs/
• z3c: http://docs.carduner.net/z3c-tutorial/

缺省theme 修改版

• Advanced Generic Widgets: http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
• Bazaar: http://doc.bazaar.canonical.com/en/
• Chaco: http://code.enthought.com/projects/chaco/docs/html/
• Djagios: http://djagios.org/
• GetFEM++: http://home.gna.org/getfem/
• GPAW: https://wiki.fysik.dtu.dk/gpaw/
• Grok: http://grok.zope.org/doc/current/
• IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
• LEPL: http://www.acooke.org/lepl/
• Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
• NOC: http://redmine.nocproject.org/projects/noc
• NumPy: http://docs.scipy.org/doc/numpy/reference/
• Peach^3: http://peach3.nl/doc/latest/userdoc/
• PyLit: http://pylit.berlios.de/
• Sage: http://sagemath.org/doc/
• SciPy: http://docs.scipy.org/doc/scipy/reference/
• simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html
• Sprox: http://sprox.org/
• TurboGears: http://turbogears.org/2.0/docs/
• Zentyal: http://doc.zentyal.org/
• Zope: http://docs.zope.org/zope2/index.html
• zc.async: http://packages.python.org/zc.async/1.5.0/

Sphinxdoc theme

• Fityk: http://fityk.nieto.pl/
• MapServer: http://mapserver.org/
• Matplotlib: http://matplotlib.sourceforge.net/
• Music21: http://mit.edu/music21/doc/html/contents.html
• MyHDL: http://www.myhdl.org/doc/0.6/
• NetworkX: http://networkx.lanl.gov/
• Pweave: http://mpastell.com/pweave/
• Pyre: http://docs.danse.us/pyre/sphinx/
• Pysparse: http://pysparse.sourceforge.net/
• PyTango: http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
• Reteisi: http://www.reteisi.org/contents.html
• Satchmo: http://www.satchmoproject.com/docs/dev/
• Sphinx: http://sphinx.pocoo.org/
• Sqlkit: http://sqlkit.argolinux.org/
• Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
• Total Open Station: http://tops.berlios.de/
• WebFaction: http://docs.webfaction.com/

内置专题－Builtin theme

• C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
• Distribute: http://packages.python.org/distribute/ (nature)
• Jinja: http://jinja.pocoo.org/ (scrolls)
• jsFiddle: http://doc.jsfiddle.net/ (nature)
• pip: http://pip.openplans.org/ (nature)
• Programmieren mit PyGTK und Glade (German): http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
• Spring Python: http://springpython.webfactional.com/current/sphinx/index.html (nature)
• sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html (agogo)
• Sylli: http://sylli.sourceforge.net/ (nature)
• libLAS: http://liblas.org/ (nature)

定制theme－网站集成

• Blender: http://www.blender.org/documentation/250PythonDoc/
• Blinker: http://discorporate.us/projects/Blinker/docs/
• Classy: classy: http://classy.pocoo.org/
• Django: http://docs.djangoproject.com/
• e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
• Flask: http://flask.pocoo.org/docs/
• Flask-OpenID: http://packages.python.org/Flask-OpenID/
• Gameduino: http://excamera.com/sphinx/gameduino/
• GeoServer: http://docs.geoserver.org/
• Glashammer: http://glashammer.org/
• MirrorBrain: http://mirrorbrain.org/docs/
• nose: http://somethingaboutorange.com/mrl/projects/nose/
• ObjectListView: http://objectlistview.sourceforge.net/python
• Open ERP: http://doc.openerp.com/
• OpenLayers: http://docs.openlayers.org/
• PyEphem: http://rhodesmill.org/pyephem/
• German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
• Pylons: http://pylonshq.com/docs/en/0.9.7/
• PyMOTW: http://www.doughellmann.com/PyMOTW/
• pypol: http://pypol.altervista.org/ (celery)
• qooxdoo: http://manual.qooxdoo.org/current
• Roundup: http://www.roundup-tracker.org/
• Selenium: http://seleniumhq.org/docs/
• Self: http://selflanguage.org/
• Tablib: http://tablib.org/
• SQLAlchemy: http://www.sqlalchemy.org/docs/
• tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
• tipfy: http://www.tipfy.org/docs/
• Werkzeug: http://werkzeug.pocoo.org/docs/
• WFront: http://discorporate.us/projects/WFront/

网站－Homepages

• Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
• A personal page: http://www.dehlia.in/
• Benoit Boissinot: http://bboissin.appspot.com/
• lunarsite: http://lunaryorn.de/
• Red Hot Chili Python: http://redhotchilipython.com/
• The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
• VOR: http://www.vor-cycling.be/

Sphinx－书籍

• The repoze.bfg Web Application Framework
• A Theoretical Physics Reference book
• Simple and Steady Way of Learning for Software Engineering(in Japanese)
• Expert Python Programming(Japanese translation)
• Pomodoro Technique Illustrated(Japanese translation)