Building the documentation locally

Sphinx

Sphinx is a Python documentation generator.

If your using the wiseEnvironment Conda environment, Sphinx should already be installed. The wiseEnvironment includes the sphinx-autobuild package, which allows you to automatically rebuild and preview your documentation in a web browser as you edit it (see next section).

Before building the documentation, ensure your Conda environment is activated:

source activate wiseEnvironment

“Live build”

Note

This is the recommended option during development.

If you are actively writing or editing documentation, the best way to preview your changes is using sphinx-autobuild. This will start a local web server and automatically refresh your browser whenever you save a file.

• Start the autobuild server.

  Navigate to the root of your project and run:

  sphinx-autobuild docs docs/_build/html
  

  (Note: If your Sphinx source files are in a different directory than `**docs**`, adjust the paths accordingly).

• View the docs:

  Open your web browser and navigate to the local URL provided in the terminal (usually http://127.0.0.1:8000).

• Use CTRL+C to stop the autobuild.

• If port 8000 is already in use by another application:

  sphinx-autobuild docs docs/_build/html --port 9000
  

Standard HTML Build

If you just want to generate the static HTML files once without starting a persistent server, you can use the standard build command.

• Build the HTML files:

  Navigate to your documentation directory (usually docs/) and run:

  make html
  

  (On Windows, use `.make.bat html` instead).

• View the docs

  Open the generated index.html file in your browser. You can typically find it at:

  docs/_build/html/index.html