sphinx-needs integration¶

The extension configures sphinx-needs to load IDs from other qualification documents. The following nodes are available:

The following link types are also available to create relationships between needs:

New custom nodes and link types can be added as needed in sphinx_needs_support.py.

Defining and linking to IDs¶

Our qualification documents contain IDs defining every concept and item referenced across our qualification material for example - RUSTC_ERR_DRIVER_04. The ferrocene_qualification Sphinx extension provides a directive and a role to respectively declare and link to an ID.

To declare a new ID, you can use the id directive:

.. id:: FOO

That directive will define an ID named FOO, and it will render it as “Identifier: FOO” (inside of tables it will just render it as “FOO” to reduce clutter).

To link to an ID, you can use the id role:

:id:`FOO`

This will create a link pointing to the definition you created earlier. Note that linking to IDs works transparently across all of our qualification material, without having to mention the document the ID was defined in. You can just reference an ID defined in a different document like you would link to an ID defined in the same document.

.. default-domain:: qualification

Using substitutions¶

Across our documentation there are terms or phrases referenced multiple times. Substitutions allow you to create “aliases” for common phrases you can include in any qualification document.

Substitutions are defined in the ferrocene/doc/sphinx-substitutions.toml file. There are also the following substitutions, which are calculated dynamically:

• doc_title: the name of the document (e.g. Safety Manual)

• doc_short_title: the acronym of the document (e.g. SM)

• ferrocene_version: the Ferrocene version number (e.g. 23.06.0)

• rust_version: the Rust version number (e.g. 1.68.2)

• channel: the Ferrocene channel of this release (e.g. stable-23.06)

You can refer to substitutions by surrounding the substitution name with |:

|doc_title|

Mentioning targets¶

When you need to refer to targets across the documentation, it’s better to use a human-readable name (like “Armv8-A bare-metal”) than the target triple, as the latter is often inconsistent between similar targets and could be confusing to customers.

To keep the target names consistent, you can use the :target: role with the target triple as its content, which will be rendered as the human-readable name:

:target:`x86_64-unknown-linux-gnu`

The :target-with-triple: role will also add the triple following the human-readable name, which is best used when customers then need to copy/paste the triple:

:target-with-triple:`aarch64-unknown-none`

The human-readable names are stored in ferrocene/doc/target-names.toml, and referring to a target not defined in that file will emit a warning.

Document ID¶

The extension is responsible for generating the ID of the document, which is displayed at the bottom of every page. The ID contains the acronym of the document and a hash of the content, uniquely identifying the revision of the document. This is enabled by default and requires no maintainer action.

Signature outcome page¶

The extension is responsible for generating the dynamic page showing the signature status of the document (see Digital signatures for more information about signatures). This is enabled by default and requires no maintainer action.

Defining CLI options¶

CLI options can be defined with the cli:program directive, whose argument is the name of the binary being documented.

Within it, you need to define one or more cli:option directives. The argument of the directive is the name of the option, with the user-provided value wrapped between <>. The body of the directive is the documentation of the CLI option:

.. cli::program: rustc

   .. cli::option: --target <name>

      Used to specify the target triple.

   .. cli::option: --help

      Show the help message.

Linking to CLI options¶

It’s possible to link to CLI options (even defined in other documents) with the :cli:option: role. Options are identified with both the program name and the option name, separated by a space. It works like a normal link role, so you can either put the option name as the role value, or arbitrary text (with the option name between <>).

:cli:option:`rustc --help`
:cli:option:`the target flag <rustc --target <name>>`

Continuous numbering of sections¶

By default Sphinx numbers pages within a toctree directive without considering other directives. This means adding multiple toctrees (for example to group some pages together) would reset the numbering, potentially having multiple pages numbered “1”.

The extension patches Sphinx to fix this, and ensure that the page numbers constantly increase even when multiple toctree directives are present.

Appendices support¶

The extension adds a new appendices directive, with the same syntax and functionality as the toctree directive. The only difference is that pages are numbered with letters rather than digits.

Rendering a template with the test outcomes¶

The render-outcomes-template directive allows rendering a Jinja template with the test outcomes of a tested target. The directive accepts a single argument, the path to the template to render. It also accepts multiple options:

• host (required): the target triple of the host platform

• target (required): the target triple of the compilation target

• bare_metal_test_target (optional): the target triple of the special target used for bare metal testing; it should be omitted if no special target was used

• remote_testing (optional): whether the tests were executed on CI or on a remote machine/emulator; its presence without a value means true, while its absence means false

.. render-outcomes-template:: templates/tests.jinja2
   :host: x86_64-unknown-linux-gnu
   :target: x86_64-unknown-linux-gnu

.. render-outcomes-template:: templates/tests.jinja2
   :host: x86_64-unknown-linux-gnu
   :target: aarch64-unknown-none
   :bare_metal_test_target: aarch64-unknown-ferrocenecoretest
   :remote_testing:

Rendering a summary of all test outcome pages¶

The render-summary directive renders a table with all render-outcomes-template invocations present in the rest of the document. It accepts no arguments nor options.

Marking releases as upcoming¶

The extension allows marking a page as upcoming by adding :upcoming-release: before any content of the page (except for comments). This adds an “upcoming” badge next to the title, and a caution message just below the title.

Including Rust changelogs¶

It is possible to inject the Rust changelog for a range of versions with the rust-changelog directive. The directive requires the :from: and :to: options to define the (inclusive) range of releases to include:

.. rust-changelog::
   :from: 1.68.2
   :to: 1.76.0