Shared artifacts concerning the Human Cell Atlas (HCA) Data Coordination Platform (DCP)
Contents
The documentation in this repository is formatted using reStructuredText
(.rst).
If you're new to reStructuredText, check out the quick reference to get started, or the reStructuredText specifications for more specific questions.
Hard-wrap paragraphs at 80 columns. Not doing so creates long lines that are hard to review.
Each document must have a document title.
Separate paragraphs with one empty line. Separate top level sections with four empty lines, and lower level sections with two. The visual aid helps delineate sections when reading the source. Like Markdown, reStructured Text is a compromise between a complete abstraction of presentational concerns and the fact that the document source is read by humans, too, not just machines.
Don't manually enumerate footnotes. Use the automatic numbering using
[#]_. This makes it much easier to insert footnotes and move sections
around.
Do manually enumerate ordered lists.
Define hyperlink targets in close proximity to their first use i.e. directly below the paragraph or at the end of the sub section. This makes it easier to move sections around and to match hyperlink and target in the source.
Emulate existing conventions.
A Github action automatically performs a reStructuredText syntax check to help ensure the documentation is correctly formatted. To run this check on your system, it is recommended to first set up a Python virtual environment:
python -m venv .venv
Then activate the virtual environment by running
source .venv/bin/activate
Install the linter:
pip install rstcheck
You might want to install the exact same version as the one referenced in the Github action. As long as the virtual environment is active, the syntax check can be performed by running
rstcheck -r .