Building the mongo-c-driver Documentation Pages
This documentation is rendered using Sphinx. To easily ensure that all tooling matches expected versions, it is recommended to use Poetry to install and run the required tools.
Tip
Poetry itself may be installed externally, but can also be automatically
managed using the included wrapping scripts for Bash (At tools/poetry.sh)
or PowerShell (at tools/poetry.ps1). These scripts can stand in for
poetry in any command written below.
Setting Up the Environment
To install the required tooling, use the poetry install command, enabling
documentation dependencies:
$ poetry install --with=docs
This will create a user-local Python virtualenv that contains the necessary
tools for building this documentation. The poetry install command only needs
to be run when the pyproject.toml file is changed.
Running Sphinx
Poetry can be used to execute the man/sphinx-build command:
$ poetry run sphinx-build -b dirhtml "./src/libmongoc/doc" "./_build/docs/html"
This command will generate the HTML documentation in the _build/docs/html
subdirectory.
Tip
Because Sphinx builds many pages, the build may run quite slowly. For faster
builds, it is recommended to use the --jobs <sphinx:sphinx-build.--jobs>
command-line option when invoking sphinx:man/sphinx-build.
Viewing the Documentation
To quickly view the rendered HTML pages, a simple local HTTP server can be
spawned on the command line by using Python's built-in
http.server module:
$ poetry run python -m http.server --directory=_build/docs/html
By default, this will serve the documentation at http://127.0.0.1:8000, which you can open in any web browser to see the rendered pages.