Documenting The Core

Documenting the Origen API is much like documenting any other Origen Application. The same principles and commands applicable there apply here as well. When running commands inside of the core itself, it functions as a dummy application named core - complete with its own config/application.toml and application.py.

As with any existing application, Origen already has some content and other extensions configured outside of the defaults yielded by origen new.

For details on the implementation of the documentation components, such as the origen sphinx extension or Shorthand, see the notes on the documentation generation implementation.

Documentation Overview

Origen’s documentation primarily uses RST, though markdown is also acceptable and should have much of the same features available thanks to Recommonmark’s embedded RST.

Configured Extensions

The Origen core activates a few other extensions not necessarily activated in a standard origen new workspace:

• Shorthand - Provides shorthand notation for shorter and single-source referencing within Sphinx apps.

  • In addition to Origen’s shorthand defs, the core application has its own set available for internal use defined in web/source/_conf/shorthand.py.

• autosectionlabel - Automatically creates references to sections.

  • To prevent clashing (which will happen with the API generation), the configuration variable autosectionlabel_prefix_document is set to True and influences how sphinx references are resolved. For example, this section is referenced as guides/developers/documenting_the_core:Configured Extensions instead of just as documenting_the_core:Configured Extensions.

• inheritance diagram - Generates an inheritance diagram in the generated API.

  • This extension uses Graphviz under the hood, which is another third-party tool for visualizing and displaying graphs.

  • At least on Windows (and at the time of this writing), this tool must be installed manually from Graphviz’s website. Since most classes are simplistic, using the extension is not required for release docs, but the extension is available otherwise.

• napoleon - Allows for docstrings formatted according to the Google Docstring Spec or Numpy Docstring Spec, or any combinations of the two (along with standard Autodoc or Sphinx Python Domain tags, which are automatically support by Origen applications).

• extlinks - Allows for tracking and referencing of external links and should be used over direct references.

  • The extlinks config variable references the full dictionary defined in web/source/conf/extlinks.py.

• RustDoc - A home-brewed sphinx extension that automates generating and moving Rust documentation into the core website’s _static directory. See the RustDoc API for additional details.

Internal Referencing

Referencing sections of Origen’s documentation within Origen should use either Sphinx’s :ref: role or Shorthand referencing, which wraps aforementioned role. Both will itself launch consistency checks when building to ensure the references are valid and flag any broken ones. Using Shorthand is preferred as any shared references can be updated in bulk if needed, but using sphinx references directly is acceptable otherwise.

Sphinx references unfortunately do not work outside of RST sources, or parts of sources parsed as RST. Shorthand provides some utilities for retrieving references usable outside of just RST sources. See the template helpers for details.

Various examples can also be found within Origen’s ‘guides/’ source.

External Referencing

The usage of direct links is discouraged in favor of extlinks, which allows tracking of external links and (eventually) some more robust link-checking over Sphinx’s nitpicky option. External links in any non-user facing places is alright, as they won’t be checked anyway, such as internal code comments (i.e, comments not in the docstring) or READMEs that are not included by the Sphinx app.

The extlinks dictionary is split from the main conf.py to help with organization and is located, along with the Origen core shorthand defs, in :origen_core_guides__conf_dir_src:src_code:_conf_dir <>.

Documenting The View (python/origen/origen)

Documenting the user-facing origen module comes in two flavors: the API, and the guides (this site!).

All user-facing methods and classes should have a docstring, which is picked up by AutoAPI and Autodoc, and keeps the API complete and available as a quick reference for method prototypes, general usage, etc.

Larger and more complex features, especially widely used, or core, ones (such as Timesets, Pins, Bits, or Registers) will need more detail than what can be provided easily by just a docstring. For these features, pages can be added to this site. Its a judgement call as to whether just docstrings are sufficient by themselves, but some form of API record should be present for all user-facing methods, even for features which will have dedicated guides. Features that do have dedicated guides should also have links to the appropriate API locations.

The output generated by Autodoc will be parsed as normal RST, meaning extlinks, Shorthand, and jinja are all available inside docstrings - and many user-facing features take advantage of this. See the origen mod or the origen_sphinx_extension sources for examples.

Sphinx’s Napoleon extension is available for docstrings formatted per the Google Docstring Spec or Numpy Docstring Spec as well.

Documenting The Controller (rust/pyapi)

The notes above apply here as well, just with the caveat that the docstrings reside in Rust instead of Python. AutoAPI will create RST files from the compiled code, but there’s no difference between those and ones generated from the origen Python module. All of the same features are available - including extlinks, Shorthand, jinja, and Google/Numpy formatted docstrings.

AutoAPI will pick up docstrings defined using Rust’s syntax on any pyclass, pyfunction, pymodule, etc.

The only caveat known so far is that AutoAPI cannot discern method or function signatures from compiled code and instead shows these as accepting no arguments, which obviously isn’t always the case. Autodoc will, however, take the first line of the docstring, if it is the function/method name, as the signature override and we can use this to fill in the gap ourselves. See this stack-overflow question for details or the tester controller source for examples within the Origen core.

Note: this requires the appropriate config variable to be set, which it is by default.

Although the controller isn’t meant to be user-facing, it is still available. Its not as imperative to document as user-facing features but is still good to have some kind of docstrings in place to make it easier on those developing core features.

Documenting The Model (rust/origen)

The model does not have any user-facing API, though documentation is still available for developers to reference. Documenting the model should follow any Rust documentation standards. Like the frontend though, complex concepts may be more easily documented on this site. For these though, documentation should reside in the developers section.