mirror of
https://github.com/ROCm/ROCm.git
synced 2026-01-09 14:48:06 -05:00
165 lines
6.0 KiB
Markdown
165 lines
6.0 KiB
Markdown
# Building documentation
|
|
|
|
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:
|
|
|
|
```sh
|
|
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 Code
|
|
|
|
One can put together a productive environment to author documentation and also
|
|
test it locally using Visual Studio (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`
|
|
|
|
```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`
|
|
|
|
```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.
|