Configuring

Sphinx Project Setup

The Sphinx source files should be placed in a directory in the same repository with the Cargo.toml and source code being documented.

The Sphinx project should also be configured to use a Makefile. The sphinx-quickstart setup tool includes dialogue for generating a Makefile which corresponds to the selected Sphinx layout.

For an existing Sphinx project, you may wish to run the sphinx-quickstart setup tool in a temporary directory retrospectively to create the Makefile.

$ sphinx-quickstart

Alternatively, you can adapt the Makefile for this project which is at github.com/woofwoofinc/cargo-sphinx/blob/master/docs/Makefile.

It is useful to configure the Sphinx project to include the Sphinx extension for GitHub Pages. This will create .nojekyll files in the output. This is required in GitHub Pages to bypass Jekyll processing, otherwise Sphinx files and directories which start with underscores will be purged. (Jekyll convention does not copy these to the final site.)

Either select the githubpages option in the sphinx-quickstart dialogue or include the following in the conf.py for your Sphinx project.

extensions = [
    'sphinx.ext.githubpages',
]

Cargo Sphinx has you covered and will create .nojekyll files in the generated output if they are not present.

Cargo Sphinx Options

You may choose any directory for the Sphinx source files. Cargo Sphinx uses docs at the top level as the default but can be easily configured in Cargo.toml or by commandline invocation parameters to use another location.

Options for Cargo Sphinx can be set in Cargo.toml under the custom section package.metadata.sphinx:

  • docs-path: string, location of the project Sphinx documentation files. Default “docs”.
  • commit-message: string, a commit message template for doc import. Default “(cargo-sphinx) Generate docs.”.
  • sign-commit: bool, use GPG to sign git commits. Default false.
  • push-remote: string, git remote for push. Default “origin”.
  • push-branch: string, default branch to push docs. Default “gh-pages”.

The following is an example of how this section appears in Cargo.toml.

[package.metadata.sphinx]
docs-path = "docs"
commit-message = "(cargo-sphinx) Generate docs."
sign-commit = false
push-remote = "origin"
push-branch = "gh-pages"

Overrides to defaults and Cargo.toml configuration can be specified when running the Cargo Sphinx commandline tool.