In the future we will flesh out this page with a guide to RFCs, but in the
meantime the RFC process is outlined in the
Implementation section of RFC 1.
Author guidelines
This repository uses Sphinx to publish a ReadTheDocs site at https://ngff.openmicroscopy.org in the Pydata Theme.
MyST syntax can be used in addition to basic Markdown and HTML.
Many flavors of markdown exist. I.e., the ngff-spec page uses Jupyter Book and the ngff website (this page) uses Sphinx.
To make sure that all used markdown stylings and syntax styles are compatible,
please find below a few guidelines for writing markdown in the ngff-spec repository.
Note
Please don’t let I don’t understand the markdown syntax stop you from contributing!
If you have a suggestion for a change to the website or specification but are not sure how to write it in markdown,
please just write it in plain markdown and we can help you with the formatting.
Referencing
The specification uses MyST extensively for a number of formatting options
to make the text readable and improve structure.
MyST allows a number of ways to reference and cross-reference inside this text
and across several of the pages in this repo.
For an overview of supported referencing syntax,
see the MyST doc pages.
It is recommended to use the following syntax in this document for consistency:
anchor: (your-reference-name)=
reference: [This is a reference](#your-reference-name)
This way, your cross-references will always resolve to the correct page,
even if the location of the markdown file changes in the future.
For cross-referencing in the spec document,
make sure to prepend the reference anchor with versionX like so:
## Some header
(version0.9:some-header)=
Otherwise, the same anchors may not be possible to resolve
if multiple versions of the spec document are built and viewed together (i.e., the anchor (ngff-spec: some_anchor) may exist in multiple documents).
Highlighting
If you refer to fields or values that would appear in JSON files,
please use backticks to highlight them, like so:
The `multiscales` field contains an array of dictionaries.
You may still use bold, italics or quotation marks for emphasis where appropriate,
but please use backticks for JSON fields and values.
Citations
ngff-spec relies on sphinxcontrib-bibtex for citations.
To add a citation to the text, add it as a bibtex entry in the references.bib file in the root of this repository.
You can then cite it in the text using the following syntax:
This is a citation {cite:t}`citation_key`.
where citation_key is the key of the bibtex entry in the references.bib file.
Json examples
We suggest using dropdowns for example code and other highlighting.
For examples, please use the following syntax to wrap your examples:
:::{dropdown} Example
Some informative text about your example
```json
"key": "value"
```
:::
which results in
Some informative text about your example
If you want to link in example metadata from somewhere in this repo (i.e, a json file),
use this syntax:
:::dropdown Example
Some informative text about your example
```{literalinclude} path/to/example.json
:language: json
:linenos:
:tab-width: 2
```
:::
Other useful admonitions and directives (e.g., hint, note) can be found here.
Building only the spec document
The spec document under the ngff-spec repository can be built as a standalone document to make writing and rendering a smoother experience.
To build the spec document, you first need to install the necessary dependencies:
After cloning the ngff-spec repo, navigate into the repository on your machine and install the dependencies using pip:
cd path/to/ngff-spec
pip install -e .
This document uses jupyter-book to generate the pages
and MyST markdown for formatting.
After installing these via the dependencies,
navigate into the repository on your machine and build the book using the following command:
python pre_build.py
jupyter book start
This autogenerates some of the markdown files (examples, schemas) and starts a local server to view the book.
Comment on a Request For Comment (RFC)#
If you want to leave a suggestion or comment on an RFC that is under review, please leave a comment in a new page under the “comments/” directory for the relevant RFC. A template is also available for formatting your comment: template.