Sphinx configuration and libraries for Safari Books Online documentation
Safari technical documentation is now being written and collected in a form that can be processed by Sphinx, a utility for generating documentation in HTML, PDF, Epub, and other formats from text files using reST (reStructuredText) wiki markup. In addition to writing docs directly, we can have Sphinx grab API documentation from our core programming languages:
Web service APIs can be documented using httpdomain from sphinx-contrib.
pip install sbo-sphinx
sbo-sphinx uses the standard Sphinx conf.py file, but offloads the vast majority of the configuration to an sbo_sphinx.conf module which should be appropriate for most SBO projects. Hence a minimal docs/conf.py file can be as simple as:
from sbo_sphinx.conf import * project = 'my_project_name'
There should also be a docs/index.rst file to serve as the documentation home page; see the one in this project for an example.
Use the standard sphinx-build syntax. For the usual case of wanting to generate the documentation in HTML format:
sphinx-build -b html . _build
reStructuredText not inside the docs directory hierarchy can’t be directly included in a table of contents. To include a README.rst file from the repository’s root directory in the generated documentation, create a placeholder inside the docs directory which uses an include directive to pull in its content:
.. include:: ../README.rst
For an example, see docs/readme.rst in this project.
If PyPI encounters something it doesn’t know how to handle in a reStructuredText package description, it just silently shows it as plain text instead of formatting it as expected. To get some warning of this before uploading your package, install the readme package and run:
python setup.py check --restructuredtext --strict
Note that for this to work, long_description must be set in setup.py (usually by loading it from a README.rst file or such). If you instead count on setting description-file in setup.cfg, the reStructuredText that will be used for the PyPI page isn’t available to the check command.
Sphinx currently has no real support for Markdown-style wiki markup. If a project has a README.md which you want to include in the documentation, there are a few options:
sbo-sphinx was written to be mostly compatible with the Read the Docs service, but keep in mind that private source code repositories cannot be used on the public Read the Docs service (but can be on a suitably configured private installation).
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|File Name & Checksum SHA256 Checksum Help||Version||File Type||Upload Date|
|sbo_sphinx-2.2.0-py2.py3-none-any.whl (1.0 MB) Copy SHA256 Checksum SHA256||py2.py3||Wheel||Sep 22, 2015|
|sbo-sphinx-2.2.0.tar.gz (965.1 kB) Copy SHA256 Checksum SHA256||–||Source||Sep 22, 2015|