Writing Documentation¶

This short guide concerns documentation in the Vinyl Cache source tree under doc/sphinx as well as basically any document on the website, where Additional Considerations for the Website apply.

This document contains the actual RST as well as code blocks with the same RST again to make the RST source visible on the rendered version.

Please try to follow this advice. Existing documentation oftentimes does not, in which case it would be nice if you updated it to follow this guide first and in a separate commit, such that RST corrections can be reviewed seperately from content changes.

Inline Markup¶

Please try to be consistent with inline markup and fix places which do not follow the style:

VCL language and other literals as literal:

VCL language and other literals as ``literal``

placeholders and emphasis as emphasis:

placeholders and emphasis as *emphasis*

no interpreted text except where it actually is that:
```
no `interpreted text` except where it actually *is* that
```
- exception: Links to manpages outside Vinyl Cache as man(section):
```
exception: Links to manpages outside vinyl as `man(section)`::
```
see Reference

use code blocks for:

use code blocks for::

        Examples and

        other code

References are tricky¶

To build html documentation, we want to create cross-document cross-references using:

:ref:`reference name`

Trouble is that rst2man and rst2pdf working on individual files cannot parse ref roles to anything outside the current rst file, so we need to differentiate link targets depending on the kind of documentation:

set link targets on the top of documents ending up in man-pages following the manpage naming scheme, e.g.:
```
.. _vinyld(1):
```
set link targets for important paragraphs following the scheme ref-doc-section, for instance:
```
.. _ref-vinyld-opt_T:
```
These can be referenced from other documents making up the html documentation, but not from stand-alone documents (like man-pages).
in all documents which are used to create man-pages, add the following definition at the top:
```
.. role:: ref(emphasis)
```
This will allow the use of ref in a compatible manner, IF references follow the man-page naming scheme
to be compatible both with sphinx and rst2man, use implicit link targets in stand-alone documents, like this one creating References are tricky:
```
`References are tricky`_
```

Document Structure¶

While RST supports a great deal of flexibility for adornments of titles and section headers, we should adhere to a consistent style to avoid breaking the document structure unintentionally.

Within the Vinyl-Cache project, we should use these characters:

Over and underline = for document titles:
```
=====
Title
=====
```
Over and underline - for document subtitles:
```
--------
Subtitle
--------
```
Underline = for sections:
```
Section
=======
```
Underline - for subsection:
```
Subsection
----------
```
Underline ~ for subsubsections:
```
Subsubsection
~~~~~~~~~~~~~
```

This is in line with the example in the RST quickstart guide

Admonitions¶

To point out particularly relevant aspects, admonitions can and should be used. They all introduce a block with:

.. <xxx>::

with xxx being one of the following:

Attention

attention

Caution

caution

Danger

danger

Error

error

Hint

hint

Important

important

Note

note

Tip

tip

Warning

warning

title

admonition:: title

Additional Considerations for the Website¶

Treat the website like a blog¶

The website has an rss feed, which is automatically updated for all pages which contain a :date: interpreted text role, such as:

:date: 2026-03-13

Consequently, new articles should be created in a seperate document. The top level index.rst should have a headline and a short teaser, linking to that document.

Updated articles should have their date updated only if there are relevant additions.

Linking on the homepage¶

When adding something to the homepage, please add the title and the date as follows:

Title
-----
.. rubric:: 2026-03-13
   :class: date

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Example:

Title¶

2026-03-13

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Sphinx differences¶

The website is not rendered in one piece, rather everything under Documentation is rendered from doc/sphinx of all the contained releases. We try to give the website and documentation a unified look and feel and sphinx is configured similarly for both, but not identical.

The most relevant difference is that the website has sphinx-design enabled, which gives us additional components.

Sphinx design¶

Please see sphinx-design for examples for all the available components.

Here we only give some examples copied from there.

Dropdowns¶

Important

Only on the website

source:

.. dropdown::

    Dropdown content

.. dropdown:: Dropdown title

    Dropdown content

.. dropdown:: Open dropdown
    :open:

    Dropdown content

Tabs¶

Important

Only on the website

Label1

Content 1

Label2

Content 2

source:

.. tab-set::

    .. tab-item:: Label1

        Content 1

    .. tab-item:: Label2

        Content 2

Badges¶

Important

Only on the website

plain badge

primary, primary-line

secondary, secondary-line

success, success-line

info, info-line

warning, warning-line

danger, danger-line

light, light-line

dark, dark-line

source:

:bdg:`plain badge`

:bdg-primary:`primary`, :bdg-primary-line:`primary-line`

:bdg-secondary:`secondary`, :bdg-secondary-line:`secondary-line`

:bdg-success:`success`, :bdg-success-line:`success-line`

:bdg-info:`info`, :bdg-info-line:`info-line`

:bdg-warning:`warning`, :bdg-warning-line:`warning-line`

:bdg-danger:`danger`, :bdg-danger-line:`danger-line`

:bdg-light:`light`, :bdg-light-line:`light-line`

:bdg-dark:`dark`, :bdg-dark-line:`dark-line`

Cards¶

Important

Only on the website

Header

Card Title

Card content

Footer

source:

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer