origen.web#

Wrappers, helpers, and utilities for Origen’s documentation system

Web commands invoked from the origen web will end up at :meth:run_cmd, which wraps the sphinx-build command or whatever else the command is. run_cmd() can also be invoked directly to kick of website compilations, etc. from scripts.

Functions in this module are, themselves, not tied to a Sphinx runtime but instead defer all sphinx-interfacing to the origen sphinx extension.

Assuming Origen’s sphinx app is used, the settings here will be loaded during origen_sphinx_extension.setup() and applied during origen_sphinx_extension.apply_origen_config()

Submodules#

Functions#

  • advertised_hostname(): Return the hostname a remote developer should use to reach this machine.

  • clean(): Runs clean on any extension which supports it.

  • get_sphinx_config_out_of_app(): Uses introspection/metaprogramming principles to discern Sphinx’s conf.py

  • release(): General purpose release script that should cover basic cases.

  • run_cmd(): Entry point for the web command. The subcommand and any arguments will be processed here then handed off

  • run_sphinx(): Launches the Sphinx-build command with the necessary options and monitors the output.

  • serve_addresses(): Return the bind address and user-facing hostname for web serve.

  • serve_static(): Serve a built site without live reload on older Python versions.

  • site_built(): Returns true if some static site pages are found in the applications web output directory. False otherwise.

  • sphinx_autobuild_cmd(): Build the sphinx-autobuild command for the live documentation server.

  • sphinx_cmd(): Given that we’re running web:build, processes the arguments and returns a command executing sphinx build with

  • sphinx_extension_mods(): Returns a list of Sphinx extensions currently in conf.py as the actual modules.

  • sphinx_extensions(): Returns a list of Sphinx extensions currently in conf.py as strings.

  • sphinx_make(): Returns the path to the makefile created from sphinx quickstart

  • view_cmd(): Undocumented.

origen.web.advertised_hostname()#

Return the hostname a remote developer should use to reach this machine.

The short hostname often resolves to a loopback entry on Linux (for example 127.0.1.1), so it is not trustworthy on its own. Consult the routing table for the outward-facing address and prefer its reverse-DNS name.

origen.web.clean(args=None)#

Runs clean on any extension which supports it.

Supporting clean just means that the extension responds to a clean method.

origen.web.get_sphinx_config_out_of_app()#

Uses introspection/metaprogramming principles to discern Sphinx’s conf.py content without actually running Sphinx. This will not pick up content which is added dynamically during the build phases. This is only to get the user’s ``conf`` contents.

origen.web.release(src=None, name=None, location=None, archive_id=None, archive_offset='archive', archive_only=False)#

General purpose release script that should cover basic cases.

In the general sense, releasing the webpages amounts to just moving the contents somewhere and optionally performing some RC check-in function.

Will leverage much of the RC driver for this so that the flow is just:

  1. Populate the repo

  2. Move the contents into the repo

  3. Check the repo back in

If the release-location is just a path, then steps 1 & 2 can be skipped.

The offset within either the path or repo will be the website_release_name with the ‘archive/{archive-ID}’ prefixed, if applicable.

# With release location = 'path/to/release/to and offset = 'o2' and no archive indicated
release_dir => path/to/release/to/o2

# With the above and an archive ID = 'dev1'
release_dir => path/to/release/to/archive/o2/dev1

# With the above and a given archive offset = 'my/archives/'
release_dir => path/to/release/to/my/archives/o2/dev1
origen.web.run_cmd(subcommand, args)#

Entry point for the web command. The subcommand and any arguments will be processed here then handed off to the proper functions for execution.

Provided this function is kept in sync with origen web, everything else should fall into place (or give necessary errors instead of just doing nothing).

origen.web.run_sphinx(args)#

Launches the Sphinx-build command with the necessary options and monitors the output. If the build is successful, returns the output path. Otherwise, returns the output.

origen.web.serve_addresses(args)#

Return the bind address and user-facing hostname for web serve.

origen.web.serve_static(args)#

Serve a built site without live reload on older Python versions.

origen.web.site_built()#

Returns true if some static site pages are found in the applications web output directory. False otherwise. The phrase ‘some static sites pages are found’ is defined to mean <website_output_dir>/build/index.html exists.

origen.web.sphinx_autobuild_cmd(args)#

Build the sphinx-autobuild command for the live documentation server.

origen.web.sphinx_cmd(args)#

Given that we’re running web:build, processes the arguments and returns a command executing sphinx build with the proper context.

origen.web.sphinx_extension_mods() → List[ModuleType]#

Returns a list of Sphinx extensions currently in conf.py as the actual modules.

Notes

  • This does not actually run sphinx, so this is based on introspection only. Extensions which dynamically add other extensions will not be discovered here.

See also

origen.web.sphinx_extensions() → [<class 'str'>]#

Returns a list of Sphinx extensions currently in conf.py as strings.

Notes

  • This does not actually run Sphinx, so this is based on introspection only. Extensions which dynamically add other extensions will not be discovered here.

See also

origen.web.sphinx_make()#

Returns the path to the makefile created from sphinx quickstart

origen.web.view_cmd()#