|
| 1 | +# Changes to the specification |
| 2 | +(contributing:spec)= |
| 3 | + |
| 4 | +Any suggested major changes to the `OME-Zarr` specification should be opened as |
| 5 | +request for comment (RFC) documents. |
| 6 | + |
| 7 | +In the future we will flesh out this page with a guide to RFCs, but in the |
| 8 | +meantime the RFC process is outlined in the |
| 9 | +[Implementation section of RFC 1](../rfc/1/index.md#implementation). |
| 10 | + |
| 11 | +## Comment on a Request For Comment (RFC) |
| 12 | + |
| 13 | +If you want to leave a suggestion or comment on an RFC that is under review, |
| 14 | +please leave a comment in a new page under the "comments/" directory for the |
| 15 | +relevant RFC. A template is also available for formatting your comment: |
| 16 | +[template](../rfc/1/templates/review_template). |
| 17 | + |
| 18 | +## How to change the specification |
| 19 | + |
| 20 | +To make a change such as the end-product of an RFC or a minor correction to the currently developed specification version, |
| 21 | +please do so via a pull request (PR) against the `main` branch of the [ome/ngff-spec](https://github.com/ome/ngff-spec) repository. |
| 22 | +Such a PR can contain a change of any of the following components of the ngff-spec repo: |
| 23 | + |
| 24 | +- The spec text itself (`ngff-spec/index.md`) |
| 25 | +- The schemas (`ngff-spec/schemas/`) |
| 26 | +- Example json metadata (`ngff-spec/examples/`) |
| 27 | + |
| 28 | +## Author guidelines |
| 29 | + |
| 30 | +This repository uses Sphinx to publish a ReadTheDocs site at https://ngff.openmicroscopy.org in the [Pydata Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/). |
| 31 | +[MyST](https://myst-parser.readthedocs.io/en/latest/) syntax can be used in addition to basic Markdown and HTML. |
| 32 | + |
| 33 | +Many flavors of markdown exist. I.e., the ngff-spec page uses [Jupyter Book](https://jupyterbook.org) and the ngff website (this page) uses [Sphinx](https://www.sphinx-doc.org/en/master/). |
| 34 | +To make sure that all used markdown stylings and syntax styles are compatible, |
| 35 | +please find below a few guidelines for writing markdown in the [ngff-spec](https://github.com/ome/ngff-spec) repository. |
| 36 | + |
| 37 | +```{note} |
| 38 | +Please don't let *I don't understand the markdown syntax* stop you from contributing! |
| 39 | +If you have a suggestion for a change to the website or specification but are not sure how to write it in markdown, |
| 40 | +please just write it in plain markdown and we can help you with the formatting. |
| 41 | +``` |
| 42 | + |
| 43 | +### Text format |
| 44 | + |
| 45 | +Contributions should conform to [Semantic Line Breaks (SemBr)](https://sembr.org/), |
| 46 | +to improve change tracking. |
| 47 | + |
| 48 | +### Referencing |
| 49 | + |
| 50 | +The specification uses [MyST](https://mystmd.org) extensively for a number of formatting options |
| 51 | +to make the text readable and improve structure. |
| 52 | + |
| 53 | +MyST allows a number of ways to reference and cross-reference inside this text |
| 54 | +and across several of the pages in this repo. |
| 55 | +For an overview of supported referencing syntax, |
| 56 | +see the [MyST doc pages](https://mystmd.org/guide/cross-references). |
| 57 | +It is recommended to use the following syntax in this document for consistency: |
| 58 | + |
| 59 | +```markdown |
| 60 | +anchor: (your-reference-name)= |
| 61 | +reference: [This is a reference](#your-reference-name) |
| 62 | +``` |
| 63 | + |
| 64 | +This way, your cross-references will always resolve to the correct page, |
| 65 | +even if the location of the markdown file changes in the future. |
| 66 | + |
| 67 | +For cross-referencing in the spec document, |
| 68 | +make sure to prepend the reference anchor with `versionX` like so: |
| 69 | + |
| 70 | +```markdown |
| 71 | +## Some header |
| 72 | +(version0.9:some-header)= |
| 73 | +``` |
| 74 | + |
| 75 | +Otherwise, the same anchors may not be possible to resolve |
| 76 | +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). |
| 77 | + |
| 78 | +### Highlighting |
| 79 | + |
| 80 | +If you refer to fields or values that would appear in JSON files, |
| 81 | +please use backticks to highlight them, like so: |
| 82 | + |
| 83 | +```markdown |
| 84 | +The `multiscales` field contains an array of dictionaries. |
| 85 | +``` |
| 86 | + |
| 87 | +You may still use bold, italics or quotation marks for emphasis where appropriate, |
| 88 | +but please use backticks for JSON fields and values. |
| 89 | + |
| 90 | +### Citations |
| 91 | + |
| 92 | +ngff-spec relies on [sphinxcontrib-bibtex](https://pypi.org/project/sphinxcontrib-bibtex/) for citations. |
| 93 | +To add a citation to the text, add it as a bibtex entry in the `references.bib` file in the root of this repository. |
| 94 | +You can then cite it in the text using the following syntax: |
| 95 | + |
| 96 | +```markdown |
| 97 | +This is a citation {cite:t}`citation_key`. |
| 98 | +``` |
| 99 | + |
| 100 | +where `citation_key` is the key of the bibtex entry in the `references.bib` file. |
| 101 | + |
| 102 | +### Json examples |
| 103 | + |
| 104 | +We suggest using [dropdowns](https://mystmd.org/guide/dropdowns-cards-and-tabs) for example code and other highlighting. |
| 105 | +For examples, please use the following syntax to wrap your examples: |
| 106 | + |
| 107 | +`````markdown |
| 108 | +:::{dropdown} Example |
| 109 | + |
| 110 | +Some informative text about your example |
| 111 | +```json |
| 112 | +"key": "value" |
| 113 | +``` |
| 114 | +::: |
| 115 | +````` |
| 116 | + |
| 117 | +which results in |
| 118 | + |
| 119 | +:::{dropdown} Example |
| 120 | + |
| 121 | +Some informative text about your example |
| 122 | +```json |
| 123 | +"key": "value" |
| 124 | +``` |
| 125 | +::: |
| 126 | + |
| 127 | +If you want to link in example metadata from somewhere in this repo (i.e, a json file), |
| 128 | +use this syntax: |
| 129 | + |
| 130 | +`````markdown |
| 131 | +:::dropdown Example |
| 132 | + |
| 133 | +Some informative text about your example |
| 134 | +```{literalinclude} path/to/example.json |
| 135 | +:language: json |
| 136 | +:linenos: |
| 137 | +:tab-width: 2 |
| 138 | +``` |
| 139 | +::: |
| 140 | +````` |
| 141 | + |
| 142 | +Other useful admonitions and directives (e.g., `hint`, `note`) can be found [here](https://mystmd.org/guide/directives). |
| 143 | + |
| 144 | +## Building *only* the spec document |
| 145 | + |
| 146 | +The spec document under the [ngff-spec](github.com/ome/ngff-spec) repository can be built as a standalone document to make writing and rendering a smoother experience. |
| 147 | +To build the spec document, you first need to install the necessary dependencies: |
| 148 | + |
| 149 | +After cloning the ngff-spec repo, navigate into the repository on your machine and install the dependencies using pip: |
| 150 | + |
| 151 | +```bash |
| 152 | +cd path/to/ngff-spec |
| 153 | +pip install -e . |
| 154 | +``` |
| 155 | + |
| 156 | +This document uses [jupyter-book](https://jupyterbook.org) to generate the pages |
| 157 | +and [MyST](https://mystmd.org) markdown for formatting. |
| 158 | +After installing these via the dependencies, |
| 159 | +navigate into the repository on your machine and build the book using the following command: |
| 160 | + |
| 161 | +```bash |
| 162 | +python pre_build.py |
| 163 | +jupyter book start |
| 164 | +``` |
| 165 | + |
| 166 | +This autogenerates some of the markdown files (examples, schemas) and starts a local server to view the book. |
0 commit comments