Development docs - minor improvements

docs/source/conf.py

@@ -57,6 +57,7 @@
     "sphinx_click.ext",
     "sphinx_tabs.tabs",
     "sphinx_copybutton",
+    "myst_parser",
 ]
 
 intersphinx_mapping = {
@@ -77,7 +78,10 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ".rst"
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # source_parsers = {'.md': MarkdownParser}
 

docs/source/dev/README.rst

@@ -29,7 +29,7 @@ learn how to `create a branch <https://docs.github.com/en/pull-requests/collabor
 and `request a review <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review>`_.
 
 If you are not sure where or how to start contributing to COMPASS, consider reaching out to the
-current developer(s): **Paul Pinchuk** ["ppinchuk@nlr.gov"] or **Guilherme Pimenta Castelao** ["gpimenta@nlr.gov"].
+current developer(s): **Paul Pinchuk** ["ppinchuk@nlr.gov"] or **Guilherme Castelao** ["gpimenta@nlr.gov"].
 
 When you are ready to contribute to COMPASS, clone a copy of the COMPASS repository from GitHub, check out your
 own branch, and make the appropriate changes locally. Ensure that your new code adheres to all of the guidelines
@@ -121,6 +121,7 @@ Use the following import conventions::
    import numpy as np
    import pandas as pd
 
+Note that ``ruff`` will monitor and enforce some style rules such as ordering of imports.
 
 Test coverage
 -------------
@@ -132,13 +133,13 @@ You can run python COMPASS tests locally using ``pixi``:
 
 .. code-block:: shell
 
-    pixi r -e ptest tests-p
+    pixi run -e ptest tests-p
 
 To speed up testing, the tests can be run in parallel using ``-n auto``:
 
 .. code-block:: shell
 
-    pixi r -e ptest tests-p -n auto
+    pixi run -e ptest tests-p -n auto
 
 Tests for a module should ideally cover all code in that module,
 i.e., statement coverage should be at 100%, though this alone does not ensure that

examples/parse_existing_docs/README.md

@@ -2,9 +2,9 @@
 
 This directory contains examples/tutorials to help you parse local documents using ``COMPASS``.
 
-- [`Parsing via CLI`](./CLI): Example showing how to parse local documents via the CLI
+- {doc}`Parsing via CLI <./CLI/README>`: Example showing how to parse local documents via the CLI
   using a typical ``COMPASS`` configuration file.
-- [`Parsing via Code`](./code): Tutorial using the ``COMPASS`` Python API to write code that
+- {doc}`Parsing via Code <./code/README>`: Tutorial using the ``COMPASS`` Python API to write code that
   parses a local PDF file.
 
 For rendered versions of these guides, see the

pyproject.toml

@@ -79,6 +79,7 @@ doc = [
   "sphinx-copybutton>=0.5",
   "sphinx-tabs>=3.4",
   "sphinxcontrib-mermaid>=1.2.3,<2",
+  "myst-parser>=5.0.0,<6",
 ]
 anthropic = [
   "anthropic>=0.40.0,<0.41",
@@ -248,6 +249,7 @@ sphinx-click = ">=6.1.0,<7"
 sphinx-copybutton = ">=0.5.2,<0.6"
 sphinx-tabs = ">=3.4.1,<4"
 sphinxcontrib-mermaid = ">=1.2.3,<2"
+myst-parser = ">=5.0.0,<6"
 
 [tool.pixi.feature.python-anthropic.dependencies]
 anthropic = ">=0.40.0,<0.41"