openpgp-notes/CONTRIBUTING.md

Contributing

These are the contribution guidelines for "Notes on OpenPGP."

Development takes place at https://codeberg.org/openpgp/notes.

Discussion around this project takes place in #notes-on-openpgp:matrix.org on Matrix.

Providing changes

This project uses sphinx and MyST-parser to allow building various output formats, such as HTML and EPUB, for the included book projects.

Contributors can provide changes by pull request towards the project.

Requirements

The following packages need to be installed on the system in order for the build to suceed:

• inkscape
• make
• myst-parser
• sphinx
• sphinxext-opengraph

Required fonts:

• Montserrat
• Noto

Optional test/check dependencies:

• codespell
• lychee
• epubcheck
• watchexec

Building and testing

The included book projects can be built and tested using a Makefile.

The below examples show how to use it with a book named book.

To cleanly build the HTML output:

$ make -C book clean build

To cleanly build the EPUB output:

$ make -C book clean epub

To spell check all files using codespell:

$ make -C book codespell

To check the external links in all HTML files using lychee:

$ make -C book html-linkcheck

Writing text

The syntax follows what is available in MyST-parser.

---

NOTE: It is advisable to always relate to the MyST-parser documentation, as MyST itself offers more/ different features!

---

Including files

It is advisable to include external files with data, instead of using a code block to display the data.

---

NOTE: The reason for this is, that codespell is used to check for common spelling mistakes and output from other programs may contain text, that will trigger it to flag it as an error.

To work around this issue, codespell is configured to ignore example files, so that not entire chapter files have to be ignored.

---

Use the {literalcode} directive to include files:

```{literalinclude} examples/my-example.txt
:language: text
```

Cross-referencing

There are a few guidelines when it comes to cross-referencing, which work around oddities with sphinx and MyST-parser:

• When adding explicit targets, use kebab case.
• Do not rename already released explicit targets, as it will break deep linking by downstreams relying on these targets.
• When referencing chapters by file, use [](/my-chapter), instead of relying on explicit targets for a top-level heading.
• To reference a figure by its title, use [](#my-figure) for a figure with the :name: attribute my-figure (and e.g., the title My Figure).
• To reference a figure by number (e.g. Fig. 1), use {numref}`my-figure` for a figure with the :name: attribute my-figure.

Figures

Figure environments must have a :name: attribute, prefixed with fig-, so that they can be referenced elsewhere. The :alt: attribute should explain what is displayed in the picture, as this is an accessibility feature. To keep matters brief, components and symbols that are described in other figures already, can be referenced by name instead of explaining them in detail.

Glossary

This project defines terms in a glossary. Using the term role, it is possible to reference these terms from anywhere. Given a term My Term in the glossary, it is possible to reference it directly using {term}`my term```` or indirectly {term}`something else````.

There are a few rules, that should be kept in mind when creating terms and referencing them.

• alternative terms for a term may exist in the glossary for completeness (e.g., My Other Term may point to My Term in the glossary)
• references to a term should always point to the deepest redirect (e.g., if My Other Term points to My Term in the glossary, references should point to My Term and not My Other Term)
• even if links to external resources can also be found in a section that is related to a term, the links related to the term should also be present in the glossary

License

All text contributions fall under the terms of the CC-BY-SA-4.0.

Configuration file contributions fall under the terms of the CC0-1.0.