Documentation#

This chapter describes how to contribute to icalendar’s documentation, including narrative documentation and docstrings in Python code which get rendered into the API reference documentation.

Find open Documentation isues

Documentation prerequisites#

Documentation builds 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](https://developer.apple.com/xcode/resources/), then install its command line tools. On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), 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

Documentation builds#

All build and check commands use the file Makefile at the root of the repository.

To see descriptions of the builds, use the following command.

make help

Else you can open the Makefile file to see other build formats.

The following sections describe the most frequently used make commands.

All make commands that build documentation will

  • create a Python virtual environment, and

  • install requirements.

html#

To build the documentation as HTML, run the following command.

make html

You can now open the output from docs/_build/html/index.html.

livehtml#

livehtml rebuilds documentation as you edit its files, with live reload in the browser.

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

linkcheckbroken#

linkcheckbroken checks all links, returning a list of only broken links.

make linkcheckbroken

Open docs/_build/linkcheck/output.txt for the entire list of links that were checked and their result.

vale#

vale checks for American English spelling, grammar, and syntax, and follows the Microsoft Writing Style Guide. See {ref}`authors-english-label` for configuration.

make vale

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

Advanced Vale usage#

You can pass options to Vale in the VALEOPTS and VALEFILES environment variables. In the following example, you can 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.md"

The command make vale automatically installs Vale into your Python virtual environment—which is also created via any documentation Makefile commands—when you invoke it for the first time.

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

icalendar configures Vale in three 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 {file}`docs/styles/config/vocabularies/icalendar/reject.txt`.

  • You can add additional spellings to accept or reject in their respective files inside the {file}`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.

clean#

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.

make clean

clean-python#

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

apidoc#

apidoc generates source documentation files from which Sphinx will render the API documentation.

make apidoc

When editing icalendar’s Python source code, use Google Python Style Guide for the docstring format. The following is an example that will render properly.

def fetch_smalltable_rows(
    table_handle: smalltable.Table,
    keys: Sequence[bytes | str],
    require_all_keys: bool = False,
) -> Mapping[bytes, tuple[str, ...]]:
"""A one-line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

Args:
    table_handle:
        An open ``smalltable.Table`` instance.
    keys:
        A sequence of strings representing the key of each table row to
        fetch.  String keys will be UTF-8 encoded.
    require_all_keys:
        If True only rows with values set for all keys will be returned.

Returns:
    A dict mapping keys to the corresponding table row data
    fetched. Each row is represented as a tuple of strings. For
    example:

    .. code-block:: python

        {b'Serak': ('Rigel VII', 'Preparer'),
        b'Zim': ('Irk', 'Invader'),
        b'Lrrr': ('Omicron Persei 8', 'Emperor')}

    Returned keys are always bytes.  If a key from the keys argument is
    missing from the dictionary, then that row was not found in the
    table (and require_all_keys must have been False).

Raises:
    IOError:
        An error occurred accessing the smalltable.

Example:
    The following is an example of using ``fetch_smalltable_rows``.

    .. code-block: pycon

        >>> fetch_smalltable_rows(my_table_handle, (b'Serak', b'Zim', b'Lrrr'))
        {b'Serak': ('Rigel VII', 'Preparer'),
        b'Zim': ('Irk', 'Invader'),
        b'Lrrr': ('Omicron Persei 8', 'Emperor')}

"""

See also

sphinx-apidoc