Build and check documentation#

This chapter describes how to build and check the quality of documentation.

Prerequisites#

You’ll need to first install prerequisites on, and clone the icalendar repository to, your local computer.

Documentation builds and checks require that you install GNU Make and uv.

Make#

Make is used to provide an interface to developers to perform repetitive tasks with a single command.

Make comes installed on most Linux distributions. On macOS, you must first install Xcode, then install its command line tools. On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include Make.

Finally, it is a good idea to update your system’s version of Make, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update Make.

uv#

uv is used for installing Python, creating a Python virtual environment, and managing dependencies for documentation.

Install uv. Read the console output for further instructions, and follow them, if needed.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

See also

Other uv installation methods

Clone repository#

To clone the icalendar repository, open a terminal session, and use the following command.

git clone https://github.com/collective/icalendar.git

Change your working directory into the cloned project.

cd documentation

File locations#

Narrative documentation files are located in the docs directory.

API reference documentation files are located in the src directory.

Make commands#

With all prerequisites installed, you can make various documentation builds, perform quality checks, and clean your environment. All Make commands use the file Makefile at the root of the repository.

The Make commands may invoke Sphinx, uv, Vale, shell commands, and other programs.

Help#

To get help and see descriptions of the make commands, use the following command.

make help

Alternatively, the Makefile file at the root of the repository contains all available commands.

All commands except the “clean” commands will create a Python virtual environment, and install requirements.

Live HTML preview#

livehtml rebuilds documentation as you edit its files, providing a preview with live reload in the browser. This is the most useful command when editing documentation.

make livehtml

The console will give you the URL to open in a web browser.

[sphinx-autobuild] Serving on http://127.0.0.1:8050

HTML#

To build the documentation as HTML without live reload, run the following command.

make html

You can now open the output file _build/html/index.html in a web browser to view static content.

This build must be successful in the Continuous integration checks for your pull request to be merged.

Spelling, grammar, and style#

vale checks American English spelling, grammar, and syntax, and follows the Microsoft Writing Style Guide.

make vale

Observe the output and adjust Vale’s configuration, as described in the next section.

Vale options#

Pass options to Vale in the VALEOPTS and VALEFILES environment variables. In the following example, run Vale to display warnings or errors only, not suggestions, in the console on a single file.

make vale VALEOPTS="--minAlertLevel='warning'" VALEFILES="docs/index.rst"

The command make vale automatically installs Vale into your Python virtual environment when you invoke it the first time.

This build must be successful in the Continuous integration checks for your pull request to be merged.

Vale integration#

Vale has integrations with various IDEs. Integration might require installing Vale using your operating system’s package manager.

Vale configuration#

icalendar configures Vale in the following places:

  • .vale.ini is Vale’s configuration file. This file allows overriding rules or changing their severity. It’s configured to use the Microsoft Writing Style Guide for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences.

  • Makefile passes options to the vale command, such as the files Vale checks.

  • icalendar documentation uses a custom spelling dictionary, with accepted and rejected spellings in docs/styles/config/vocabularies/icalendar/. Authors should add new words and proper names using correct casing to docs/styles/config/vocabularies/icalendar/accept.txt, sorted alphabetically and case-insensitive.

    If Vale does not reject a spelling that should be rejected, then you can add it to docs/styles/config/vocabularies/icalendar/reject.txt.

    All entries in both files support regular expressions. Use https://regex101.com/ with the Golang option selected to test regular expressions.

    See also

    Vale’s regex guide

  • Add generic spellings to accept or reject in their respective files inside the docs/styles/config/vocabularies/Base/ folder.

Because it’s difficult to automate good American English grammar and syntax, it’s not strictly enforced.

You can add spellings to Vale’s configuration, and submit a pull request. This is an easy way to become a contributor to icalendar.

Test code snippets and docstrings#

To run tests on code snippets and docstrings, use the following command.

make doctest

This is a shortcut that calls pytest to run on a single test file.

Build API source files#

apidoc generates source documentation files from which Sphinx will render the API documentation. This command should be used when either:

  • adding a new module, that is, a Python file in the src/icalendar directory

  • changing the options of source reStructuredText files to build API documentation

make apidoc

See also

sphinx-apidoc

Purge builds#

clean removes all builds and cached files of the documentation. Use this command before a build to troubleshoot issues with edits not showing up and to ensure that cached files do not hide errors in the documentation. This is especially useful when adding a new page to the documentation and it doesn’t appear in the navigation. Sphinx only rebuilds changed files.

make clean

Purge environment#

clean-python cleans the documentation build directory and Python virtual environment. Use this command when packages that you have installed in your virtual environment yield unexpected results.

make clean-python

Add features#

To add features to documentation through Sphinx extensions and other programs, you might need to perform the following tasks.

Add a package#

To add a package for documentation, such as a Sphinx extension or other third application, use uv.

uv add --group docs new-requirement

This will add new-requirement to the list of documentation requirements in the docs group in the pyproject.toml file.

Configure a package#

Most packages require configuration in Sphinx and in the Makefile file. Follow the specific directions of the package.

For Sphinx, you would typically edit the file docs/conf.py, and add both the package’s Python name to the extensions list and its configuration options as a new section. For the latter, use a comment with a visual separator, such as that for configuring the Napolean extension.

# -- Napolean configuration ----------------------------------
napoleon_use_param = True
napoleon_google_docstring = True
napoleon_attr_annotations = True

If your feature adds a shell command, add helpful options to the Makefile file.

Document a package#

“If it ain’t documented, it’s broken.”

After adding and configuring a package, it’s important to inform other people what the feature does and how to use it.

Pull request previews#

On every pull request, Read the Docs generates a pull request preview of the documentation. It will append a link to the preview in the description of the pull request that the author creates.

View all builds of documentation on Read the Docs.

This feature is configured in the files .readthedocs.yml and .github/workflows/rtd-pr-preview.yml.

Continuous integration checks#

On every pull request, continuous integration checks attempt to build the documentation, run Vale checks, and check for broken links. If any of these checks fail, then the pull request cannot be merged. You must resolve the build failures, preferably locally, before the pull request can be merged.

This feature is configured in the file .github/workflows/documentation.yml.