Building Documentation

Building Documentation#

Applies to Linux and Windows

2023-08-08

9 min read time

While contributing, one may build the documentation locally on the command-line or rely on Continuous Integration for previewing the resulting HTML pages in a browser.

Pull Request documentation builds#

When opening a PR to the develop branch on GitHub, the page corresponding to the PR (https://github.com/RadeonOpenCompute/ROCm/pull/<pr_number>) will have a summary at the bottom. This requires the user be logged in to GitHub.

  • There, click Show all checks and Details of the Read the Docs pipeline. It will take you to a URL of the form https://readthedocs.com/projects/advanced-micro-devices-rocm/builds/<some_build_num>/

    • The list of commands shown are the exact ones used by CI to produce a render of the documentation.

  • There, click on the small blue link View docs (which is not the same as the bigger button with the same text). It will take you to the built HTML site with a URL of the form https://advanced-micro-devices-demo--<pr_number>.com.readthedocs.build/projects/alpha/en/<pr_number>/.

Build documentation from the Command Line#

Python versions known to build documentation:

  • 3.8

To build the docs locally using Python Virtual Environment (venv), execute the following commands from the project root:

python3 -mvenv .venv
# Windows
.venv/Scripts/python -m pip install -r docs/sphinx/requirements.txt
.venv/Scripts/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
# Linux
.venv/bin/python     -m pip install -r docs/sphinx/requirements.txt
.venv/bin/python     -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html

Then open up _build/html/index.html in your favorite browser.

Build documentation using Visual Studio (VS) Code#

One can put together a productive environment to author documentation and also test it locally using VS Code with only a handful of extensions. Even though the extension landscape of VS Code is ever changing, here is one example setup that proved useful at the time of writing. In it, one can change/add content, build a new version of the docs using a single VS Code Task (or hotkey), see all errors/ warnings emitted by Sphinx in the Problems pane and immediately see the resulting website show up on a locally-served web server.

Configuring VS Code#

  1. Install the following extensions:

    • Python (ms-python.python)

    • Live Server (ritwickdey.LiveServer)

  2. Add the following entries in .vscode/settings.json

    {
  "liveServer.settings.root": "/.vscode/build/html",
  "liveServer.settings.wait": 1000,
  "python.terminal.activateEnvInCurrentTerminal": true
}

    The settings above are used for the following reasons:

    • liveServer.settings.root: Sets the root of the output website for live previews. Must be changed alongside the tasks.json command.

    • liveServer.settings.wait: Tells live server to wait with the update to give time for Sphinx to regenerate site contents and not refresh before all is done. (Empirical value)

    • python.terminal.activateEnvInCurrentTerminal: Automatic virtual environment activation is a nice touch, should you want to build the site from the integrated terminal.

  3. Add the following tasks in .vscode/tasks.json

    {
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Docs",
      "type": "process",
      "windows": {
        "command": "${workspaceFolder}/.venv/Scripts/python.exe"
      },
      "command": "${workspaceFolder}/.venv/bin/python3",
      "args": [
        "-m",
        "sphinx",
        "-j",
        "auto",
        "-T",
        "-b",
        "html",
        "-d",
        "${workspaceFolder}/.vscode/build/doctrees",
        "-D",
        "language=en",
        "${workspaceFolder}/docs",
        "${workspaceFolder}/.vscode/build/html"
      ],
      "problemMatcher": [
        {
          "owner": "sphinx",
          "fileLocation": "absolute",
          "pattern": {
            "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):(\\d+):\\s+(WARNING|ERROR):\\s+(.*)$",
            "file": 1,
            "line": 2,
            "severity": 3,
            "message": 4
          },
        },
        {
          "owner": "sphinx",
          "fileLocation": "absolute",
          "pattern": {
            "regexp": "^(?:.*\\.{3}\\s+)?(\\/[^:]*|[a-zA-Z]:\\\\[^:]*):{1,2}\\s+(WARNING|ERROR):\\s+(.*)$",
            "file": 1,
            "severity": 2,
            "message": 3
          }
        }
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
  ],
}

    (Implementation detail: two problem matchers were needed to be defined, because VS Code doesn’t tolerate some problem information being potentially absent. While a single regex could match all types of errors, if a capture group remains empty (the line number doesn’t show up in all warning/error messages) but the pattern references said empty capture group, VS Code discards the message completely.)

  4. Configure Python virtual environment (venv)

    • From the Command Palette, run Python: Create Environment

      • Select venv environment and the docs/sphinx/requirements.txt file. (Simply pressing enter while hovering over the file from the drop down is insufficient, one has to select the radio button with the ‘Space’ key if using the keyboard.)

  5. Build the docs

    • Launch the default build Task using either:

      • a hotkey (default is Ctrl+Shift+B) or

      • by issuing the Tasks: Run Build Task from the Command Palette.

  6. Open the live preview

    • Navigate to the output of the site within VS Code, right-click on .vscode/build/html/index.html and select Open with Live Server. The contents should update on every rebuild without having to refresh the browser.

Contents