Merge branch 'main' of https://github.com/HUPO-PSI/mzPAF into add-sph…

…inx-docs

.gitignore

@@ -1,3 +1,4 @@
+.python-version
 .venv/
 .github/
 docs/_build/

Makefile

@@ -0,0 +1,6 @@
+
+all: publish-references
+
+publish-references:
+	cp ./specification/reference_data/reference_molecules.json ./implementations/python/mzpaf/data/reference_molecules.json
+	cd ./specification/reference_data/ && python reference_mol_to_md.py

README.md

@@ -2,13 +2,21 @@
 
 ## About
 
-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.
+mzPAF 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.
 
 - Official mzPAF homepage: [psidev.info/mzPAF](https://psidev.info/mzPAF)
 - mzPAF documentation: [mzpaf.readthedocs.io](https://mzpaf.readthedocs.io)
 
+## Status
+
+_Updated: 2024-10-15_
+
+The specification has been resubmitted to the PSI Document Process and is undergoing final
+community review. It is anticipated to become a formal PSI standard near the end of 2024.
+
 ## In short
 
 - mzPAF is a single string of characters, case sensitive, without length limit
@@ -89,24 +97,19 @@ Learn more at the
 
 ### mzPAF regular expressions
 
-[todo]
-
-### mzPAF Lark grammar
+The mzPAF specification includes regular expressions for parsing mzPAF strings. These can be used
+in any programming language that supports regular expressions.
 
-[todo]
-
-## Specification status
-
-Updated: 2023-09-01
+Learn more at the
+[mzPAF regex documentation](https://mzpaf.readthedocs.io/en/latest/implementations/regex/).
 
-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.
+### mzPAF Lark grammar
 
-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](mailto:[email protected]).
+mzPAF has also been defined as a
+[Lark grammar](https://mzpaf.readthedocs.io/en/latest/implementations/lark/).
 
 ### Links
 
-- The GitHub repo associated with mzPAF: https://github.com/HUPO-PSI/mzPAF
-- The GitHub repo associated with the related mzSpecLib standard: https://github.com/HUPO-PSI/mzSpecLib
-- HUPO-PSI homepage: https://www.psidev.info/
+- The mzPAF GitHub repo: [github.com/HUPO-PSI/mzPAF](https://github.com/HUPO-PSI/mzPAF)
+- The GitHub repo for the related mzSpecLib standard: [github.com/HUPO-PSI/mzSpecLib](https://github.com/HUPO-PSI/mzSpecLib)
+- HUPO-PSI homepage: [psidev.info](https://www.psidev.info/)

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/conf.py

@@ -100,5 +100,3 @@ def get_reference_molecules_md(input_json, output_markdown):
 
 def setup(app):
     config = {"enable_eval_rst": True}  # noqa: F841
-
-

docs/implementations/python/api.rst

@@ -2,18 +2,13 @@
 Python API
 **********
 
-.. manually documented as parse_annotation is undocumented (returned by the AnnotationStringParser
-   class)
+.. automodule:: mzpaf
+    :members:
+    :imported-members:
 
-.. function:: mzpaf.parse_annotation(annotation_string: str)
 
-   Parses an mzPAF string into a list of ion annotations.
+    .. manually documented as parse_annotation is undocumented
 
-   :param annotation_string: mzPAF string with peak annotations.
-   :type annotation_string: str
-   :returns: A list of annotations.
-   :rtype: list[mzpaf.IonAnnotationBase]
+    .. autofunction:: parse_annotation
 
-.. automodule:: mzpaf
-   :members:
-   :imported-members:
+        Parse a string into one or more :class:`IonAnnotationBase` instances.

docs/implementations/python/examples.rst

@@ -0,0 +1,14 @@
+*************
+Example Usage
+*************
+
+.. code-block:: python
+
+    import mzpaf
+
+    annotations: list[mzpaf.IonAnnotationBase] = mzpaf.parse_annotation("y1")
+
+    annot: mzpaf.PeptideFragmentIonAnnotation = annotation[0]
+    assert annot.series == 'y'
+    assert annot.position == 1
+    assert annot.charge == 1

docs/specification/index.rst

@@ -12,6 +12,5 @@ Specification document
 ..
     TODO: Add when released
 
-The latest draft of the specification can be found on
-`GitHub <https://github.com/HUPO-PSI/mzPAF/blob/main/specification/mzPAF_specification_v1.0-draft14.docx?raw=true>`_.
-
+The mzPAF specification drafts can be found on
+`GitHub <https://github.com/HUPO-PSI/mzPAF/blob/main/specification/>`_.

implementations/python/mzpaf/__init__.py

@@ -13,4 +13,4 @@
     "PrecursorIonAnnotation", "ReferenceIonAnnotation", "NamedCompoundIonAnnotation",
     "FormulaAnnotation", "SMILESAnnotation", "Unannotated", "MassError",
     "InvalidAnnotation", "parse_annotation"
-]
+]