The Origen Sphinx Extension¶

Now that you’ve been exposed to extensions, we can talk about the origen sphinx extensions, which bridges the gap between the Origen application and the Sphinx app.

As you may have seen on the Sphinx docs, extensions are capable of making certain customizations, including:

Registering config variables
Setting up config values for itself and for other extensions
Hooking into the build in various phases, such as when the config is initialized or when the builder is first initialized
Setting up themes

All of the Origen specifics, or the ‘behind the scenes work,’ is done by this extension - hooked into your Sphinx app in various phases.

The origen sphinx extensions is responsible for, but not limited to:

Listening for and enacting options from origen build.
Setting up the origen theme
Configuring recommonmark to accept embedded RST.
Allowing Jinja templating in all RST files.
Building and including OSE SubProjects

All of that is ‘behind-the-scenes’ though. The origen sphinx extensions also provides some helpful features and additional config variables.

Configuration Variables¶

The Origen extension adds these configuration variables:

origen_subprojects¶: Any Origen applications whose documentation should be built and encompassed in this. See Subproject for more details.

New in version 0.0.0.

origen_no_api¶: Indicates whether the API should be built. This is set automatically when the --no-api switch is used.

New in version 0.0.0.

SubProjects¶

Some Origen workspaces are actually a collection of applications. Or, some more functional (or plugin) applications may have a smaller, development application built into, or adjacent to, it - the latter being how the Origen project is actually setup. In applications where it is expected that one application will encompass some others, it may be more fluid for the documentation to do the same, but without actually containing that other’s Sphinx app (or Origen application for that matter).

The origen sphinx extensions has a means for one project to automate building and capturing the static webpages of one Origen application into another. This is setup by registering to-be-encompassed projects in the origen_subprojects configuration variable. Registering a project here will, during the top application’s build phase, run origen web build for the given subprojects and copy its resulting webpages into _static/origen_sphinx_ext/<subproject name>. This subproject’s webpages can now be referenced in the current app like any other static entity and shipped along with the top Origen’s application’s webpages.

# Register an Origen application which this application should build webpages for.
# The subprojects are a nested dictionary where the key is the subproject name and the source
# points to that Origen application's root (note: not the Sphinx app's root).
#  (The nested dictionary structure is to allow for future customizations to individual subprojects)
origen_subprojects = {
  'example': {
    'source': 'path/to/example/application/root,
  }
}

The Origen Theme¶

Unless the configuration says otherwise, Origen will set the current theme to origen. Origen’s theme is a modified bootstrap4 theme with darkly overlaid atop and dark-themed syntax highlighting from dracula.

Origen’s theme also includes some items not easily reachable by extensions. The origen theme options section below will give a tour of what options Origen’s theme has available.

Origen Theme Options¶

logos¶

Given logos will line the top of the navbar, starting on the left-hand side.

Base Sphinx only allows a single logo that must reside in _static and can only link to the project’s homepage. See: config.html_logo

Origen’s theme offers the ability to use multiple logos with more flexibility per logo. The logos will be appear in the order in which they are inserted

html_theme_options['logos'].append({
  # Add a logo from an external source
  'src': 'https://link_to_my_logo.png',
  'href': 'https://link_my_logo_points_to',
  'alt': 'alternative text to display if the logo cannot be found',
  'rel_src': False
})

html_theme_options['logos'].append({
  # Add a logo from a source relative to the project (such as in '_static')
  'src': '_static/my_other_logo.png',
  'href': 'https://link_my_other_logo_points_to',
  'alt': 'alternative text',
  'rel_src': True
})

New in version 0.0.0.

bypass_main_logo¶

In addition to the logos above, if a config.html_logo is not given, the project’s name with a reference pointing to the homepage is inserted as the foremost logo.

This project-level logo can be suppressed by setting bypass_main_logo to True, leaving only the theme’s logos given above.

Default:: False

html_theme_options['bypass_main_logo'] = False

New in version 0.0.0.

favicon_raw_src¶

If set to True, the favicon src will be whatever the value given is, verbatim. If False, then the favicon is assumed to reside in _static/, which is Sphinx’s default. This item has no effect if config.html_favicon is set

Default:: False

html_theme_options['favicon_raw_src'] = False

New in version 0.0.0.

favicon¶

Sphinx’s favicon, shown here, doesn’t allow for one located outside of _static

The favicon provided here can reside outside of _static, or as a URL if favicon_raw_src is set to True.

Websites can only display one favicon and Sphinx’s config.html_favicon takes priority. If config.html_favicon is set to anything other than None or False (or, technically, anything else that resolves to False), it will be used in place of anything given here.

Default:: None

# if html_theme_options['favicon_raw_src'] is set

# Direct path
html_theme_options['favicon'] = "path/to/favicon/in/_static/directory.png"

# URL
html_theme_options['favicon'] = "https://url/for/your/favicon.png"

Note: Be sure not tp confuse html_theme_options['favicon'], the theme config, with conf.html_favicon, which is a Sphinx global config variable and takes precedence over html_theme_options['favicon'].

New in version 0.0.0.

To maintain some semblance across Origen applications, a few logos will be prefixed automatically. The settings for these logos are shown below:

  [
    {
        "src": "https://origen-sdk.org/img/origen-device.png",
        "href": "https://origen-sdk.org",
        "alt": "Origen-SDK",
        "rel_src": false
    },
    {
        "src": "https://origen-sdk.org/img/origen-text.png",
        "href": "https://origen-sdk.org",
        "alt": "Origen-SDK",
        "rel_src": false,
        "style": "height: 25px;"
    }
]

Recap¶

The origen sphinx extensions:

is the bridge between your Origen application, Origen itself, and your Sphinx app.
will setup several aspects of your Sphinx app for you at runtime.
has its own set of configuration variables.
also comes with support for SubProjects
contains the origen theme
The origen theme, though part of the origen sphinx extensions, contains its own configuration options, which follows Sphinx’s rules for configuring themes, but is also accessible in your config.py via html_theme_options.

Table Of Contents

Previous topic

Next topic

The Origen Sphinx Extension¶

Configuration Variables¶

SubProjects¶

The Origen Theme¶

Origen Theme Options¶

Recap¶