Contributing documentation

Prerequisites

Before contributing to EPNix, follow the contributing Prerequisites.

Documentation philosophy

Make sure to read the Documentation philosophy, which explains how the documentation is structured and the writing style.

Building documentation

As a package

To build the documentation, run the following from EPNix’s source code directory:

Building the documentation
nix build -L ".#docs"

The HTML is then stored in ./result/share/doc/epnix/html/.

You can open a browser with xdg-open ./result/share/doc/epnix/html/index.html.

Tip

Some features aren’t available when using a web browser with files, such as link icons. If you want the documentation with these features, run:

python -m http.server 8000 -b 127.0.0.1 -d result/share/doc/epnix/html

Then open a browser at http://localhost:8000.

In a development shell

When actively writing documentation, building the epnix.docs package is slow.

You can use the docs development shell to build the documentation with make:

Building the documentation in a development shell
nix develop ".#docs"
make -C docs html

If there are issues with the sidebar or other inconsistencies, run make -C docs clean then rebuild the documentation.

Tip

For a faster edit and compile cycle, you can use the watchexec tool to automatically build the documentation when you change files:

Continuously compile the documentation
# If not already,
# enter the "docs" development shell
nix develop ".#docs"

# Leave this command running in a terminal
watchexec "make -C docs html"

You can open a browser with xdg-open docs/_build/html/index.html or run a web server with:

Start a web server for documentation built in a development shell
python -m http.server 8000 -b 127.0.0.1 -d docs/_build/html

This command starts a web server available at http://localhost:8000.

Writing style

Read Writing style in the Documentation philosophy article for general guidelines.

Vale

We recommend using Vale when writing documentation.

To install it as a command-line tool, follow Vale’s Install instructions. To install it as a Language Server, follow Vale’s LSP guide.

When writing, try to follow Vale’s advice when it makes sense.

Following every Vale rule isn’t mandatory, but it should lead to better documentation.

Sphinx and MyST’s Markdown

EPNix uses Sphinx as a documentation system and the MyST Sphinx extension to write it in Markdown.

MyST’s Markdown differs in some ways from the standard Markdown format to offer Sphinx’s features.

Read Sphinx’s documentation to learn more about the framework, features, plugins, or how to organize documents.

Read MyST’s documentation to learn about the Markdown syntax.

The following is a summary of some features.

Organizing the structure

Sphinx builds a tree of documents called a “TOC tree.” You use the toctree directive to insert child documents. For example:

```{toctree}
:maxdepth: 2

sub-document
```

Some recommendations:

  • Use the ```{toctree} Markdown syntax, not :::{toctree}.

  • Use the :maxdepth: 2 option.

  • Use the :glob: option and * as document when the general order doesn’t matter.

    Tip

    You can mix globbing and selecting articles to put first or last, for example:

    Order a single article as first
    ```{toctree}
:glob:
:maxdepth: 2

prerequisites
*
```

  • Use the :numbered: option when you want to sequence a set of articles, such as for tutorials.

Code blocks

Use the code-block directive. Use the :caption: option to describe your code extract. For example:

```{code-block} nix
:caption: An example Nix attribute set

{
  example = "Hello, world!";
}
```

Figures

Use the figure directive, for example:

```{figure} my-article/my-image.png

An example image description
```