Sphinx Intro

Sphinx documentation is written in reStructuredText (reST), a lightweight plain-text markup format, and then transformed into various output formats like HTML. If you want to learn more about using Sphinx in general, your best bet is unsurprisingly to start with the Sphinx tutorial and then read on from there.

However, if you're mainly interested in contributing to existing documentation, your first stop should be the reStructuredText Primer which explains the basics of reST. In addition, you'll want to read the section on additional Sphinx markup constructs to get an overview of any other semantic markup elements Sphinx offers.

Style Guide

• When using external links with a separate target, you should always specify an explicit identifier for the link. That means you shouldn't write your links like this:

  A paragraph with `a wrong hyperlink`_.
  
  .. _a wrong hyperlink: http://example.com
  

  Rather, you should write them like this:

  A paragraph with `a correct hyperlink <link_>`_.
  
  .. _link: http://example.com
  

  Note the extra <link_>. Not only does this form free you from having to repeat the entire text of your link, it's important for localization. Having these explicit link identifiers allows translators to translate the link text as well as rearrange links in a paragraph without messing up the link targets.

• For similar reasons, when using footnotes, don't use implicitly numbered footnotes ([#]_). Always specify an explicit footnote identifier, for example [#f1]_. You can also use more explicit names if you prefer. Don't worry about having to renumber all footnotes if you insert a new one somewhere in-between others: the ordering and numbering of your footnotes in the final document is only determined by the order of the footnote bodies at the end of the source document.

• When using replace substitutions (documentation), the replacement text is not translatable. Accordingly, only use these substitutions when the substituted text doesn't have to be translated.

• Always use appropriate semantic markup, where available, rather than just styling things with simple markup elements. So for instance, when referring to an executable program, use the program role (:program:`speedcrunch`).

• Headings should be title-cased. That means in a heading, you should capitalize

  • The first word.
  • All nouns, verbs, adjectives, adverbs, and pronouns.
  • All words that are four letters or longer.

  [title-case]

• Don't write the manual as if just for one specific version of SpeedCrunch. Instead, document when a feature was introduced or what changed between SpeedCrunch versions. This keeps the latest version of the documentation relevant even for older SpeedCrunch versions and helps avoid confusion about how the versions differ. Use the versionadded, versionchanged and deprecated directives with the SpeedCrunch version to mark the differences between versions.

The SpeedCrunch Domain

A domain in the context of Sphinx is simply a set of reST markup elements to describe related objects. [1] The SpeedCrunch domain (short name: sc) provides directives to document SpeedCrunch "objects", i.e. things like functions or constants. These are documented below with their full name, i.e. the sc: prefix. However, all documents by default use the sc domain, so it's not actually necessary to specify the prefix when using these directives. For example, to refer to a function, simply use :func:`function_name`.

All of these directives automatically create all required index entries. This includes the entries in the main index, the entries in the function index and the necessary entries for the context help feature.

.. sc:function:: function_name(arg; arg [; arg; arg; ...])

Document a SpeedCrunch function. Specify the function's signature as above, with parameters separated by ; and optional parameters enclosed in square brackets. In the body of the directive, you can use the following fields to describe specific aspects of the function:

• param, parameter, arg, argument to describe a parameter.
• returns, return to describe the return value.

A complete example looks like this:

.. sc:function:: foo(a; b [; c])

   Textual description of what the function does.

   :param a: The first parameter. Describe its role, its
             range of values, whatever you can think of.
   :param b: The second parameter.
   :param c: The third, optional parameter.
   :returns: Describe the return value.

.. sc:constant:: constant_name

Document a built-in constant.

sc:func

Link to the documentation for a built-in function. You can optionally specify the parentheses after the function name, but they aren't necessary; in the output, the link text will always include the parentheses for consistency. In text, this is used like this:

This sentence includes a reference to :sc:func:`sin`.

sc:const

Link to the documentation for a constant. This is used in text like this:

This sentence includes a reference to :sc:const:`pi`.

Tooling

The following tools are required for building the documentation:

• Python 3.4 or later
• Sphinx 1.3 or later
• the Quark theme 0.2 or later

It is recommended to install Python and pip from the Python website. or the package manager of your choice, then run:

pip install "sphinx>=1.3" "quark-sphinx-theme>=0.2"

When working with localization, you may additionally require:

• sphinx-intl
• Transifex CLI client

While writing the documentation, you can use the usual Sphinx tools to preview your progress. From the manual directory, run make html [2] to generate the HTML documentation in the _build/html directory. This will use a different theme than the integrated manual, but it's still useful for checking your markup. If you need more control, you can also invoke sphinx-build directly; see the Sphinx documentation on sphinx-build for detailed usage instructions. You can also use sphinx-autobuild to automatically update the HTML documents whenever you modify the sources.

To generate the documentation as it would be for the integrated manual, you need to pass the sc_bundled_docs tag to sphinx-build using the command-line flag -t. Most notably, this switches the theme to the one used for the bundled documentation. In general, you shouldn't need to write documentation that's different between the integrated manual and stand-alone documentation. Still, if you need to distinguish between these, you can check for the presence of the sc_bundled_docs tag. See the Sphinx documentation on tags for more information on how to use these.

doc-tool is the custom Python script used to automate certain documentation-related tasks. It can be found in the root directory of the manual in the SpeedCrunch source repository (doc/src/doc-tool.py). Its main purpose is to generate the documentation for any supported target language with a single command. In addition, doc-tool has shortcuts for certain maintainer tasks. To get an overview of supported options and commands, run doc-tool --help.

• To generate .pot files for translation, run doc-tool.py extract-strings. This runs Sphinx's gettext builder to crawl the manual's reST files as well as the custom extensions for translatable strings.
• To update the .po files, run doc-tool.py update-translations. This step is generally not needed since it's handled by Transifex.
• Run doc-tool.py build-standalone-docs or doc-tool.py build-bundled-docs to actually build the docs for all supported languages.

By default, building SpeedCrunch does not rebuild the documentation; the readme explains how to use an updated manual. To update the bundled prebuilt copy of the manual that's included with the source tree, build the update-prebuilt-manual target:

cmake <speedcrunch source dir>/doc/src
make update-prebuilt-manual

Footnotes

Citations