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.

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!

---

Cross-referencing

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

• 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.

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.