Contribute to documentation

All of the documentation on this site is built as part of the RAIL Package, and the configuration and skeleton for the documentation live in the rail/docs directory.

The documentation skeleton is set up to work with whatever RAIL packages are installed, e.g., if you are just working on one of the algorithms, you can just install that algorithm in addition to rail_base and rail and when you generate the docs you will just get the docs for rail_base and that package.

The documentation uses sphinx to automatically generate some content from the source code, this requires being very careful with docstring formatting.

The documentation tools are configured to use the numpy docstring style

The documentation uses RAIL introspection tooling to find all the RAIL code in your current python environment. rail.core.introspection.

Creating a new tutorial notebook

To create a new tutorial notebook, you can start by duplicating the template notebook provided in the rail repository. Then all you need to to is replace the template text and code with your own, and place the new notebook in one of the existing folders of notebooks. As long as you place the notebook inside one of the core_examples/, creation_examples/, estimation_examples/, evaluation_examples/, or goldenspike_examples/ folders, it should be rendered and uploaded to the RAIL documentation.

Building the RAIL documentation locally

To build the documentation locally, you must install RAIL in developer mode. To do so, refer to the Developer Installation Instructions. Once you have installed rail from source you can build all the documentation locally very easily. Note that this will also build the documentation for any and all installed rail_algorithms packages.

You may have to install the documentation requirements in RAIL first by running the following in the rail directory:

pip install .[docs]

To make the documentation, run the following:

cd rail/docs
make html

This will generate the documentation tree in rail/docs/_build/html.

You can then point a browser at the local file, e.g., rail/docs/_build/html/index.html to explore the documentation.

RAIL Introspection tools

The RailEnv class provides tools to discover and organize all the available RAIL code.

class rail.core.RailEnv

Singleton class that manages introspection into the RAIL installation

This will idenfity all of the installed RAIL packages, namespaces and files, and navigate the connections between them.

This will also generate restructed text (.rst) files for the Sphinx autodoc documentation

__init__()

classmethod __new__(*args, **kwargs)

Functions to set up the RAIL environment

classmethod RailEnv.import_all_packages(silent=False)

Import all the packages that are available in the RAIL ecosystem

Parameters:

silent (bool)

Return type:

None

classmethod RailEnv.attach_stages(to_module, silent=False)

Attach all the available stages to this module

Parameters:

• to_module (ModuleType) – python module we are attaching stages to

• silent (bool)

Return type:

None

Notes

This allow you to do:

from rail.stages import *

Functions to explore the RAIL environment

classmethod RailEnv.list_rail_packages()

List all the packages that are available in the RAIL ecosystem

Returns:

Dict mapping the package names to the path to the package

Return type:

dict[str,str]

classmethod RailEnv.print_rail_packages()

Print all the packages that are available in the RAIL ecosystem

Return type:

None

classmethod RailEnv.list_rail_namespaces()

List all the namespaces within rail

Returns:

Dict mapping the namespaces to the paths contributing to each namespace

Return type:

dict[str, list[str]]

classmethod RailEnv.print_rail_namespaces()

Print all the namespaces that are available in the RAIL ecosystem

Return type:

None

classmethod RailEnv.list_rail_modules()

List all modules within rail

Returns:

Dict mapping module names to their import paths

Return type:

dict[str, str]

classmethod RailEnv.print_rail_modules()

Print all the moduels that are available in the RAIL ecosystem

Return type:

None

classmethod RailEnv.build_rail_namespace_tree()

Build a tree of the namespaces and packages in rail

Returns:

Tree of the namespaces and packages in rail

Return type:

dict[str, list[dict]]

classmethod RailEnv.print_rail_namespace_tree()

Print the namespace tree in a nice way

Return type:

None

classmethod RailEnv.print_rail_stage_dict()

Print an dict of all the RailSages organized by their base class

Return type:

None

Functions to build the API rst files read by sphinx autodoc

classmethod RailEnv.do_api_rst(basedir='.')

Build the top-level API documentation

Parameters:

basedir (str) – Directory to write file to

Return type:

None

classmethod RailEnv.do_stage_type_api_rst(basedir='.')

Genarate the rst files for the stage tpye documentation

Parameters:

basedir (str)

Return type:

None

apidoc_utils.write_interactive_api_rst()

Write rst api files for the rail.interactive module and associated submodules

The default RailEnv api writer doesn’t understand the dynamically created submodules for interactive. Additionally, we need the :imported-members: rst directive for autodoc in order to actually render the interactive functions.

Parameters:

docs_path (str) – docs directory where Sphinx is run from

Return type:

None