origen.web.rustdoc

Simple sphinx extension for building a Rust project’s documentation, via cargo doc, and moving it into the Sphinx app.

Rust projects are added through the rustdoc_projects Sphinx configuration variable - a dict whose keys are the project names and whose values are a second dict containing that project’s configuration:

# conf.py
rustdoc_projects = {
  'project1': {
    'opt a': 'value',
    'opt b': 'value',
    # ...
  },
  'project2': {
    'opt a': 'value',
    'opt b': 'value',
    # ...
  }
  # ...
}

The following configuration options are available per-project:

• source - Required - The Rust project’s source location.

• default_build_options (True) - Adds default build options no-deps and workspace to the cargo doc command.

• rustdoc_output_dir (./) - Directory to move the resulting documentation to. Defaults to the current directory.

• apply_svg_workarounds (False) - Applies a fix for SVG images needed if releasing to github.io. See here for more details.

• build_options ({}) - Additional key-value pairs passed as arguments to cargo doc.

These Sphinx configuration variables are also available:

• rustdoc_apply_svg_workarounds (None) - Applies SVG workaround to all Rustdoc Projects, unless overridden by the project’s config.

• rustdoc_output_dir (None) - Applies this output directory to all Rustdoc Projects unless overridden by the project’s config.

Functions

• build(): Build each Rustdoc project

• setup(): Hook into sphinx just before it starts to read all the templates.

origen.web.rustdoc.build(sphinx)

Build each Rustdoc project

origen.web.rustdoc.setup(sphinx)

Hook into sphinx just before it starts to read all the templates. Add this point, we’ll build the Rust docs using ‘cargo doc’, parse the resulting contents, and create our own templates for Python-based calls.

Classes

• RustDocProject: Undocumented.

class origen.web.rustdoc.RustDocProject(proj, config)

Inheritance

BRUSH_FILE = 'C:\\Users\\nxa13790\\Documents\\origen\\o2_master\\python\\origen\\web\\rustdoc\\override\\brush.png'

BRUSH_PNG_SRC = 'brush.png'

BRUSH_SVG_SRC = 'brush.svg'

DOWN_ARROW_FILE = 'C:\\Users\\nxa13790\\Documents\\origen\\o2_master\\python\\origen\\web\\rustdoc\\override\\down-arrow.png'

DOWN_ARROW_PNG_SRC = 'down-arrow.png'

DOWN_ARROW_SVG_SRC = 'down-arrow.svg'

OVERRIDE_PATH = WindowsPath('C:/Users/nxa13790/Documents/origen/o2_master/python/origen/web/rustdoc/override')

WHEEL_FILE = 'C:\\Users\\nxa13790\\Documents\\origen\\o2_master\\python\\origen\\web\\rustdoc\\override\\wheel.png'

WHEEL_PNG_SRC = 'wheel.png'

WHEEL_SVG_SRC = 'wheel.svg'

build()

Runs the build command and moves the resulting docs into the Sphinx project space

cmd()

Returns the cargo doc command to build the project’s documentation

Returns

cargo doc command

Return type

str

fix_svg()

At the time of this implementation, github.io pages seem to dislike rendering local svg files. It doesn’t seem to have a problem with SVG in general, nor a problem with the SVGs Rust docs actually uses - just the way its referenced.

A quick workaround for this is just to convert Rust’s SVGs into PNGs and post-process the resulting html files to reference the PNGs instead. This will be done for all html files and the SVGs: brush.svg, wheel.svg, and down-arrow.svg.

SVGs were converted using this site.

mv_docs()

Copy the resulting docs from the target/doc directory into the output directory. Note: these are copied since the --target-dir option will actually rebuild the project in the new directory, which isn’t what we want. We just want the output docs.