Building documentation

2024-10-25

7 min read time

Applies to Linux and Windows

GitHub

If you open a pull request and scroll down to the summary panel, there is a commit status section. Next to the line docs/readthedocs.com:advanced-micro-devices-demo, there is a Details link. If you click this, it takes you to the Read the Docs build for your pull request.

If you don’t see this line, click Show all checks to get an itemized view.

Command line

You can build our documentation via the command line using Python.

See the build.tools.python setting in the Read the Docs configuration file for the Python version used by Read the Docs to build documentation.

See the Python requirements file for Python packages needed to build the documentation.

Use the Python Virtual Environment (venv) and run the following commands from the project root:

python3 -mvenv .venv

.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

Navigate to _build/html/index.html and open this file in a web browser.

Visual Studio Code

With the help of a few extensions, you can create a productive environment to author and test documentation locally using Visual Studio (VS) Code. Follow these steps to configure VS Code:

1. Install the required extensions:

   • Python: (ms-python.python)

   • Live Server: (ritwickdey.LiveServer)

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

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

   • 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 the live server to wait with the update in order to give Sphinx time to regenerate the site contents and not refresh before the build is complete.

   • python.terminal.activateEnvInCurrentTerminal: Activates the automatic virtual environment, so you can build the site from the integrated terminal.

3. Add the following tasks to .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 the Python virtual environment (venv).

   From the Command Palette, run Python: Create Environment. Select venv environment and docs/sphinx/requirements.txt.

5. Build the docs.

   Launch the default build task using one of the following options:

   • A hotkey (the default is Ctrl+Shift+B)

   • Issuing the Tasks: Run Build Task from the Command Palette

6. Open the live preview.

   Navigate to the site output 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.