Building Your Webpages#

This section will discuss the origen web command in more detail and cover some of the available options for origen web build.

At the very beginning, we introduced the build command: origen web build --view as a means to generate and view your project’s documentation. Now that we’ve covered more of what Origen and Sphinx have to offer, we can revisit this command and take a closer look at some of its options.

Origen Web#

The build command is actually a subcommand in the larger origen web command.

Running origen web --help will show you what can be done with the Sphinx app from the CLI:

Build and view application documentation

Usage: origen web [OPTIONS] [COMMAND]

Commands:
  build  Build the application documentation [aliases: b, compile, html]
  view   Open previously generated documentation [alias: v]
  serve  Build, watch, and serve application documentation [alias: s]
  clean  Remove generated documentation [alias: c]
  help   Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Terminal verbosity level e.g. -v, -vv, -vvv [alias: --verbosity]
      --verbosity_keywords <verbosity_keywords>
          Keywords for verbose listeners [alias: --vk]
  -t, --targets <TARGETS>...
          Override the targets currently set by the workspace for this command [alias: --target]
      --no_targets
          Clear any targets currently set by the workspace for this command [alias: --no_target]
      --mode <MODE>
          Override the default mode currently set by the workspace for this command
  -h, --help
          Print help

Building#

You should now be familiar with the build command’s basic usage, but what about some of the other options?

Running build with --help gives us the following options:

Build the application documentation

Usage: origen web build [OPTIONS]

Options:
  -v, --verbose...
          Terminal verbosity level e.g. -v, -vv, -vvv [alias: --verbosity]
      --view
          Open the generated documentation after a successful build
      --clean
          Clean generated documentation before building
      --verbosity_keywords <verbosity_keywords>
          Keywords for verbose listeners [alias: --vk]
      --no-api
          Skip Python and Rust API documentation generation
  -r, --release
          Release the generated documentation
  -a, --archive <ARCHIVE_ID>
          Archive the generated documentation under the given ID
      --as-release
          Build with release checks without publishing
      --release-with-warnings
          Allow a release build to complete with warnings
      --sphinx-args <ARGS>
          Additional arguments passed to sphinx-build
  -t, --targets <TARGETS>...
          Override the targets currently set by the workspace for this command [alias: --target]
      --no_targets
          Clear any targets currently set by the workspace for this command [alias: --no_target]
      --mode <MODE>
          Override the default mode currently set by the workspace for this command
  -h, --help
          Print help

--no-api was mentioned when discussing API generation but to recap: this option will bypass generating any API contents. Existing contents will persist though, so this option can be used without any ill-effects provided the API source hasn’t changed. However, this also means that continuously running with --no-api during development could result in stale API documentation.

Viewing And Cleaning#

For local authoring, run the live documentation server:

$ origen web serve --open

On Python 3.11 and newer this uses sphinx-autobuild to watch source files, rebuild incrementally, and live-reload the browser. Older supported Python versions build once and use Python’s built-in static server. The default serve mode includes generated API, Rustdoc, and subprojects. Use origen web serve --fast for an authored-guide-only editing loop.

By default, --host auto binds all interfaces and advertises the machine’s resolved hostname, making remote development hosts available without another option. Ensure the selected port is allowed by host and network firewalls.

Restrict the server to the local machine when remote access is not wanted:

$ origen web serve --host 127.0.0.1

The equivalent explicit remote binding is:

$ origen web serve --host 0.0.0.0 --port 8000

Generated documentation can contain internal APIs and paths, so review network and firewall policy before using 0.0.0.0.

Sphinx is makefile-like, in that it will only recompile changed files, leading to faster build times. A side-effect of this, however, is that the web browser may still be launched, even on a failing build, giving the illusion that the build succeeded.

An easy way to get around the above is just to wipe out the results and rebuild from scratch. The origen web clean command will do just that. Running this command will remove any webpages from a previous build, forcing a full recompilation. It will also run clean on any extensions which supports cleaning.

The webpages can also be built with a clean Sphinx app using origen web build --clean. This is the same as running:

origen web clean
origen web build

Likewise, the commands:

origen web clean
origen web build
origen web view

Can all be mashed into the same command as origen web build --clean --view

Releasing#

When the documentation is complete, it can be released by using the -r, or --release switch. The release procedure and location is dependent on options in the Origen application.

Warning

Releasing is a feature still in development. Pieces are working, but documentation is purposefully left scarce as certain aspects are either still in development or subject to change.

When building your docs, you may see various warnings pop up. In general, it is not good practice to leave build warnings hanging around for released content. Releasing will interpret all warnings as errors and will fail to release the docs, even if the build previously succeeded without the --release switch. However, this can be overridden by also using the release-with-warnings switch.

Releasing will also add other, long-running checks into the mix - such as checking for the validity of external links, which can take several minutes to complete for large projects. These checks can be run during a development build by applying the switch --as-release to the build command.

Archiving#

In conjunction with, or as an alternative to, releasing your docs, you can choose to archive them instead, the intent being to provide a snapshot of the documentation corresponding to a particular Origen application version.

Archiving is very similar to releasing except that the resulting build is released as a “sub-site*, meaning that the latest content, as well as other archives are unchanged and the resulting build is instead placed somewhere within the currently released site.

For example, using the archive <archive_id> option during origen web build will place the built docs at <release_path>/archive/<app name>/<archive_id> but keep the remaining <release_path> unaffected.

Recap#

origen web build is actually a subcommand of the larger origen web command.
Cleaning, building, and viewing your webpages can all be streamlined with the single command origen web build --clean --view.
In some circumstances, the webpages can still be viewed even on a failing build.
Once the docs are complete, the -r, or --release, switch can be used to release the documentation.
Similarly, the --archive <archive_id> switch can be used to instead release a snapshot of the current documentation with a particular archive id without affecting the latest or other archives.