Package: sbo-sphinx
OverviewSafari technical documentation is now being written and collected
in a form that can be processed bySphinx, 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:Python docstrings are collected using the sphinx-apidoc command.JSDoc-formatted comments in JavaScript are collected using the
JsDoc Toolkit RST-Template library, which in turn uses jsdoc-toolkit.Web service APIs can be documented using httpdomain from sphinx-contrib.Installationpip installsbo-sphinxTo build JavaScript API documentation, you’ll also need java and ant.Settingssbo-sphinx uses the standard Sphinxconf.py file,
but offloads the vast majority of the configuration to ansbo_sphinx.confmodule which should be appropriate for most SBO
projects.  Hence a minimaldocs/conf.pyfile can be as simple as:from sbo_sphinx.conf import *

project = 'my_project_name'There should also be adocs/index.rstfile to serve as the documentation
home page; see the one in this project for an example.There are additional settings for the extensions which auto-generate Python
and JavaScript API documentation. Seesbo_sphinx.apidocandsbo_sphinx.jsdocfor details.UsageUse the standardsphinx-buildsyntax.
For the usual case of wanting to generate the documentation in HTML format:sphinx-build-bhtml._buildExternal FilesreStructuredText not inside thedocsdirectory 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 thedocsdirectory which uses an include directive to
pull in its content:.. include::../README.rstFor an example, seedocs/readme.rstin this project.PyPI Description ValidationIf 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 thereadmepackage and run:python setup.py check --restructuredtext --strictNote 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 settingdescription-fileinsetup.cfg, the reStructuredText
that will be used for the PyPI page isn’t available to thecheckcommand.MarkdownSphinx 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:Convert it to README.rst instead, changing the markup accordingly.pandocmay do a reasonably good job
of automating this conversion.Add a reStructuredText-formatted copy of the file to thedocsdirectory
and include that in the documentation instead.  This does run the risk of
the copy getting out of sync with the original, however.Implement a Sphinx extension which uses pandoc to automatically convert and
copy the Markdown files specified in a configured list.  The drawback with
this approach is that it requires pandoc to be installed on each system on
which the documentation will be generated.Read the Docssbo-sphinx was written to be mostly compatible with theRead the Docsservice, 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).NotesThe table of contents page for Python modules is generated atdocs/python/index.  The equivalent file for JavaScript (if generated)
is atdocs/javascript/index, and there is also a list of processed JS
files atdocs/javascript/files.  These should be added to a toctree
directive in the documentation.  Again, see this project’sdocs/index.rstfor an example.The RST-Template library for creating reST files from JSDoc comments
currently uses jsdoc-toolkit, which is no longer in active development.  If
we decide that its successor JSDoc 3 has enough useful improvements, we can
look into updating the library to use that instead.Troubleshootingerror: unrecognized arguments- If this pops up and breaks the build while
parsing the code being documented, odds are that file has code at the module
level which usesargparseoroptparse, and it’s unsuccessfully trying
to parse the command line parameters which were given to sphinx-build.  Put
such code inside a function which is only called inside anif __name__ == '__main__'condition (i.e., if that script was the one
called).ReferencesSphinxreStructuredText syntax overviewJSDocJSDoc 3JsDoc Toolkit RST-Templatesphinx-contrib- Lots of
cool stuff here; support for CoffeeScript, Doxygen, Erlang, Excel, Google
charts and maps, RESTful HTTP APIs, Ruby, etc.sphinxcontrib.httpdomain- Documenting RESTful HTTP APIs