docs.rs Documentation Generation
Using a Dev Container Feature
Other Methods to Preview the Documentation HTML

Use just docs docall to generate the code in the docs.rs↗ format.

Note that cargo doc --open↗ does not seem to work when running from a Dev Container in VS Code; the script that opens URLs into an external browser (see $ echo $BROWSER) does not handle raw HTML. Use python3 -m http.server 9000 (or live server) to serve the files instead.

Read the justfile or the just module↗ in bk/scripts/docs for more details.

Using a Dev Container Feature

Alternatively, use the "Desktop lite" Dev Container feature↗ to install a light GUI manager. Add the following to devcontainer.json↗:

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {}
},
"forwardPorts": [
    6080
],
"portsAttributes": {
    "6080": {
        "label": "desktop"
    }
},

and the following to the Dockerfile↗.

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && apt-get install -y firefox-esr

Optionally apt-get install xdg-utils↗ to check that Firefox is the default for text/html:

xdg-mime query default text/html
# or for more details:
XDG_UTILS_DEBUG_LEVEL=2 xdg-mime query default text/html

xdg-settings --list
xdg-settings get default-web-browser

Point your browser to http://localhost:6080↗ and use vscode↗ as the password. Open the HTML file of your choice with:

xdg-open /code/target/bk/doc/deps/index.html

Other Methods to Preview the Documentation HTML

  • Right-click the /code/target/bk/doc folder in the VS Code Explorer view and select Download... or use VS Code's built-in Simple Browser command.
  • Or install the Live Server↗ or MS Live Preview VS Code extensions.