Add start for docs

.gitignore

@@ -0,0 +1,4 @@
+.venv/
+.github/
+docs/_build/
+specification/annotation-schema.md

CONTRIBUTING.rst

@@ -0,0 +1,55 @@
+############
+Contributing
+############
+
+This document briefly describes how to contribute to
+`mzPAF <https://github.com/hupo-psi/mzPAF>`_.
+
+
+
+Before you begin
+################
+
+If you have an idea for a feature, use case to add or an approach for a bugfix,
+you are welcome to communicate it with the community by opening a
+thread in `GitHub Issues <https://github.com/hupo-psi/mzPAF/issues>`_.
+
+
+
+Documentation local setup
+#########################
+
+To work on the documentation and get a live preview, install the requirements
+and run ``sphinx-autobuild``:
+
+.. code-block:: sh
+
+    pip install -r ./docs/requirements.txt
+    sphinx-autobuild  ./docs/ ./docs/_build/
+
+Then browse to http://localhost:8000 to watch the live preview.
+
+
+
+How to contribute
+#################
+
+- Fork `mzPAF <https://github.com/hupo-psi/mzPAF>`_ on GitHub to
+  make your changes.
+- Commit and push your changes to your
+  `fork <https://help.github.com/articles/pushing-to-a-remote/>`_.
+- Ensure that the tests and documentation (both Python docstrings and files in
+  ``/docs/``) have been updated according to your changes. Python
+  docstrings are formatted in the
+  `numpydoc style <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
+- Open a
+  `pull request <https://help.github.com/articles/creating-a-pull-request/>`_
+  with these changes. You pull request message ideally should include:
+
+    - A description of why the changes should be made.
+    - A description of the implementation of the changes.
+    - A description of how to test the changes.
+
+- The pull request should pass all the continuous integration tests which are
+  automatically run by
+  `GitHub Actions <https://github.com/hupo-psi/mzPAF/actions>`_.

README.md

@@ -1,17 +1,86 @@
 # mzPAF Peak Annotation Format
 
-The mzPAF proposed standard is a specification for a fragment ion peak annotation format for mass spectra, focused on peptides. This provides for a standardized format for describing the origin of fragment ions to be used in spectral libraries, other formats that aim to describe fragment ions, and software tools that annotate fragment ions.
+## About
 
-The main home page for mzPAF is at the PSI web site: https://psidev.info/mzPAF
+The mzPAF proposed standard is a specification for a fragment ion peak annotation format for mass spectra, focused on
+peptides. This provides for a standardized format for describing the origin of fragment ions to be used in spectral
+libraries, other formats that aim to describe fragment ions, and software tools that annotate fragment ions.
 
-# Status
+- Official mzPAF homepage: [psidev.info/mzPAF](https://psidev.info/mzPAF)
+- mzPAF documentation: [mzpaf.readthedocs.io](https://mzpaf.readthedocs.io)
 
-Updated: 2023-02-25
 
-The specification has been submitted to the PSI Document Process and is undergoing review. It will take several months starting January 2023 to undergo rigorous review before potentially becoming a PSI standard.
+## Specification status
 
-# Available Materials
-- The current DRAFT specification: https://github.com/HUPO-PSI/mzPAF/blob/main/specification/mzPAF_specification_v1.0-draft10.docx?raw=true
+Updated: 2023-09-01
+
+The specification has been resubmitted to the PSI Document Process and is undergoing final community review. Ratification to formally become a PSI standard is anticipated near the end of 2023.
+
+Your comments and suggestions are still very much welcome. Please submit an issue at the repo to
+provide your feedback and send an e-mail to the HUPO-PSI editor Sylvie Ricard-Blum
+([email protected]).
+
+
+## In short
+
+- mzPAF is a single string of characters, case sensitive, without length limit
+- Multiple possible explanations are separated with a comma
+- Deltas of observed – theoretical *m/z* values are prefixed with a slash (`/`)
+- Confidences can be provided for different annotations prefixed with an asterisk (`*`)
+
+The basic format of each annotation is:
+
+```
+annotation1/delta,annotation2/delta,...
+```
+
+or:
+
+```
+annotation1/delta*confidence,annotation2/delta*confidence,...
+```
+
+For example:
+
+```
+b2-H2O/3.2ppm,b4-H2O^2/3.2ppm
+```
+
+or:
+
+```
+b2-H2O/3.2ppm*0.75,b4-H2O^2/3.2ppm*0.25
+```
+
+mzPAF supports:
+
+- Annotations of multiple analytes: `1@y12/0.13,2@b9-NH3/0.23`
+- Mass deltas in ppm instead of *m/z* unit: `y1/-1.4ppm`
+- Confidence levels per annotation: `y1/-1.4ppm*0.75`
+- Advanced ion notation: `[ion type](neutral loss)(isotope)(adduct type)(charge)`, e.g.: `y4-H2O+2i[M+H+Na]^2`:
+    - Ion types:
+        - Peptide ion series (a, b, c, x, y, z): `y4`
+        - Unknown ions: `?`
+        - Immonium ions: `IY`
+        - Internal fragment ions: `m3:6`
+        - Intact precursor ions: `p^2`
+        - A set of reference ions: `r[TMT127N]`
+        - Named compounds: `_{Urocanic Acid}`
+        - Chemical formulas: `f{C16H22O}`
+        - Smiles: `s{CN=C=O}[M+H]`
+        - Embedded ProForma annotations: `0@b2{LC[Carbamidomethyl]}`
+    - Neutral gains and losses: `y2+CO-H2O`
+    - Isotopes: `y2+2i`
+    - Adduct types: `y2[M+H]`
+    - Charge states: `^2`
+- Multiple peaks per annotation: `&y7/-0.001` and `y7/0.000*0.95`
+
+Read the [full specificiation](https://mzpaf.readthedocs.io/specification) for more details and
+examples.
+
+
+### Available Materials
+- The current DRAFT specification: https://github.com/HUPO-PSI/mzPAF/blob/main/specification/mzPAF_specification_v1.0-draft14.docx?raw=true
 - The GitHub repo associated with mzPAF: https://github.com/HUPO-PSI/mzPAF
-- The GitHub repo assocated with the related mzSpecLib standard: https://github.com/HUPO-PSI/mzSpecLib
+- The GitHub repo associated with the related mzSpecLib standard: https://github.com/HUPO-PSI/mzSpecLib
 

docs/.readthedocs.yaml

@@ -0,0 +1,21 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  builder: dirhtml
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - method: pip
+      path: implementations/python
+      extra_requirements:
+        - docs