150 lines
5.8 KiB
Markdown
150 lines
5.8 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
|
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
-->
|
|
|
|
# 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](https://inkscape.org)
|
|
* `make`
|
|
* [myst-parser](https://github.com/executablebooks/MyST-Parser)
|
|
* [sphinx](https://github.com/sphinx-doc/sphinx/)
|
|
* [sphinxext-opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)
|
|
|
|
Required fonts:
|
|
|
|
* [Montserrat](https://github.com/JulietaUla/Montserrat)
|
|
* [Noto](https://fonts.google.com/noto)
|
|
|
|
Optional test/check dependencies:
|
|
|
|
* [codespell](https://github.com/codespell-project/codespell)
|
|
* [lychee](https://lychee.cli.rs/)
|
|
* [epubcheck](https://github.com/w3c/epubcheck)
|
|
* [watchexec](https://github.com/watchexec/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:
|
|
|
|
```shell
|
|
$ make -C book clean build
|
|
```
|
|
|
|
To cleanly build the [EPUB] output:
|
|
|
|
```shell
|
|
$ make -C book clean epub
|
|
```
|
|
|
|
To spell check all files using [codespell]:
|
|
|
|
```shell
|
|
$ make -C book codespell
|
|
```
|
|
|
|
To check the external links in all [HTML] files using [lychee]:
|
|
|
|
```shell
|
|
$ 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](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#including-code-from-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<My Term>````.
|
|
|
|
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].
|
|
|
|
[`#notes-on-openpgp:matrix.org`]: https://matrix.to/#/%23notes-on-openpgp%3Amatrix.org
|
|
[Matrix]: https://matrix.org
|
|
[sphinx]: https://www.sphinx-doc.org/en/master/
|
|
[MyST-parser]: https://myst-parser.readthedocs.io/en/latest/
|
|
[HTML]: https://en.wikipedia.org/wiki/HTML
|
|
[EPUB]: https://en.wikipedia.org/wiki/EPUB
|
|
[MyST]: https://mystmd.org/guide/quickstart-myst-markdown
|
|
[codespell]: https://github.com/codespell-project/codespell
|
|
[lychee]: https://lychee.cli.rs
|
|
[explicit targets]: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#creating-explicit-targets
|
|
[kebab case]: https://en.wikipedia.org/wiki/Letter_case#Kebab_case
|
|
[Figure]: https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#figures-images-with-captions
|
|
[accessibility]: https://en.wikipedia.org/wiki/Computer_accessibility
|
|
[glossary]: https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#definition-lists-and-glossaries
|
|
[CC-BY-SA-4.0]: ./LICENSES/CC-BY-SA-4.0.txt
|
|
[CC0-1.0]: ./LICENSES/CC0-1.0.txt
|