docs

EATRIS · Nov 24, 2023 · 7c260f8 · 7c260f8
1 parent 3314f76
commit 7c260f8
Show file tree

Hide file tree

Showing 12 changed files with 106 additions and 68 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -13,10 +13,6 @@ jobs:
         run:
           shell: bash -l {0}
 
-    strategy:
-      matrix:
-        python-version: ["3.11"]
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -27,14 +23,14 @@ jobs:
           auto-update-conda: true
           miniforge-variant: Mambaforge
           channels: conda-forge
-          python-version: ${{ matrix.python-version }}
-          activate-environment: motbxtest_and_doc
-          environment-file: envs/motbxtest_and_doc.yml
+          python-version: '3.11'
+          activate-environment: motbxtools_doc
+          environment-file: envs/motbxtools_doc.yml
           use-mamba: true
 
       - name: Build environment
         run: |
-          conda activate motbxtest_and_doc
+          conda activate motbxtools_doc
           python -m pip install -e .
 
       - name: Sphinx build

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -11,10 +11,6 @@ jobs:
         run:
           shell: bash -l {0}
 
-    strategy:
-      matrix:
-        python-version: ["3.11"]
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -25,14 +21,14 @@ jobs:
           auto-update-conda: true
           miniforge-variant: Mambaforge
           channels: conda-forge
-          python-version: ${{ matrix.python-version }}
-          activate-environment: motbxtest_and_doc
-          environment-file: envs/motbxtest_and_doc.yml
+          python-version: 3.11
+          activate-environment: motbxtools_test
+          environment-file: envs/motbxtools_test.yml
           use-mamba: true
 
       - name: Build environment
         run: |
-          conda activate motbxtest_and_doc
+          conda activate motbxtools_test
           python -m pip install -e .
 
       - name: Run unit tests

diff --git a/doc/builddoc.rst b/doc/builddoc.rst
@@ -13,22 +13,25 @@ The following commands can be used to create a `Conda`_ environment that contain
 
 2. Install dependencies
 
-    A. Option 1: install dependencies manually using Miniconda/Anaconda Prompt or terminal::
+   A. Option 1: install environment from `YAML environment file`_ ::
 
-            conda create -n motbxdoc python=3.11
-            conda activate motbxdoc
-            conda install -c conda-forge sphinx
-            conda install -c conda-forge furo
-            conda install -c conda-forge jsonschema
-            conda install -c conda-forge validators
-            conda install -c anaconda requests
-            conda install -c conda-forge pyyaml
-            pip install -e .
+         conda env create -f envs/motbxtools_doc.yml
+         conda activate motbxtools_doc
+         pip install -e .
 
+   B. Option 2: install dependencies manually using Miniconda/Anaconda Prompt or terminal::
 
-    B. Option 2: install environment from `YAML environment file`_ ::
+         conda create -n motbxtools_doc python=3.11
+         conda activate motbxtools_doc
+         conda install -c conda-forge furo
+         conda install -c conda-forge jsonschema
+         conda install -c conda-forge validators
+         conda install -c anaconda requests
+         conda install -c conda-forge pyyaml
+         conda install -c conda-forge sphinx
+         conda install -c conda-forge sphinx-argparse
+         pip install -e .
 
-            conda env create -f envs/motbxdoc.yml
 
 The `HTML` documentation can be built using::
 
@@ -46,6 +49,6 @@ The action is defined in `.github/workflows/documentation.yml`_ and can be manua
 .. _Conda: https://docs.conda.io/en/latest/
 .. _Miniconda3: https://docs.conda.io/projects/miniconda/en/latest/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
-.. _YAML environment file: https://github.com/EATRIS/motbx/blob/main/envs/motbxdoc.yml
+.. _YAML environment file: https://github.com/EATRIS/motbx/blob/main/envs/motbxtools_doc.yml
 .. _.github/workflows/documentation.yml: https://github.com/EATRIS/motbx/blob/main/.github/workflows/documentation.yml
 .. _actions: https://github.com/EATRIS/motbx/actions/workflows/documentation.yml
diff --git a/doc/conf.py b/doc/conf.py
@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'MOTBXtools'
+project = 'motbxtools'
 copyright = '2023, EATRIS'
 author = 'Anna Niehues'
 
@@ -31,7 +31,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'sphinxarg.ext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,9 +1,9 @@
-.. MOTBXtools documentation master file, created by
+.. motbxtools documentation master file, created by
    sphinx-quickstart on Fri Nov 10 14:22:04 2023.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to MOTBXtools' documentation!
+Welcome to motbxtools' documentation!
 ======================================
 
 .. image:: https://github.com/EATRIS/motbx/assets/1405356/cf4ddf87-a2d0-40c3-8f18-058e36885bea
@@ -17,7 +17,8 @@ Welcome to MOTBXtools' documentation!
    motbx
    schema
    modules
-   usemotbxtools
+   utilities
+   installation
    builddoc
    contribute
 

diff --git a/doc/usemotbxtools.rst → doc/installation.rst b/doc/usemotbxtools.rst → doc/installation.rst
@@ -1,7 +1,7 @@
-Use `MOTBXtools` and Jupyter notebooks
-======================================
+Install `motbxtools` and use example notebooks
+==============================================
 
-Several Jupyter notebooks using the `MOTBXtools` Python library are provided as
+Several Jupyter notebooks using the `motbxtools` Python library are provided as
 part of the `MOTBX GitHub repository`_. We make use of `Conda`_ for cross-platform
 package management.
 
@@ -13,7 +13,13 @@ Install Conda environment
 
 2. Install dependencies
 
-   A. Option 1: install dependencies manually using Miniconda/Anaconda Prompt or terminal
+   A. Option 1: install environment from `YAML environment file`_ ::
+
+         conda env create -f envs/motbxtools_notebooks.yml
+         conda activate motbxtools_notebooks
+         pip install -e .
+
+   B. Option 2: install dependencies manually using Miniconda/Anaconda Prompt or terminal
 
       i. Install `notebook` and Jupyter kernels (`nb_conda_kernels`) to Conda base environment::
 
@@ -22,10 +28,10 @@ Install Conda environment
 
       ii. Create new environment and register kernel for Jupyter::
 
-            conda create -n motbxtools python=3.11
-            conda activate motbxtools
+            conda create -n motbxtools_notebooks python=3.11
+            conda activate motbxtools_notebooks
             conda install ipykernel
-            python -m ipykernel install --user --name=motbxtools --display-name "Python 3.11 (motbxtools)"
+            python -m ipykernel install --user --name=motbxtools_notebooks --display-name "Python 3.11 (motbxtools_notebooks)"
             conda install -c anaconda requests
             conda install -c conda-forge pyyaml
             conda install -c conda-forge jsonschema
@@ -34,10 +40,7 @@ Install Conda environment
             conda install -c conda-forge keyring
             conda install -c anaconda pandas
             conda install -c conda-forge openpyxl
-
-   B. Option 2: install environment from `YAML environment file`_ ::
-
-         conda env create -f envs/motbxtools.yml
+            pip install -e .
 
 
 Run Jupyter
@@ -47,20 +50,21 @@ Jupyter can now be started from the base environment::
 
    jupyter notebook
 
-This opens Jupyter in your default browser. Select a notebook from the `notebooks`_ folder to open it.
+This opens Jupyter in your default browser. Select a notebook from the
+`notebooks`_ folder to open it.
 
 
-Notebooks
----------
+Example Jupyter Notebooks
+-------------------------
 
-A set of `Jupyter notebooks`_ showcase how `MOTBXtools` can be used to create/modify
+A set of `Jupyter notebooks`_ showcase how `motbxtools` can be used to create/modify
 the MOTBX resource schema and validate resources.
 Make sure to run them from the `notebooks`_ directory.
 
 
 .. _MOTBX GitHub repository: https://github.com/EATRIS/motbx
 .. _Conda: https://docs.conda.io/en/latest/
 .. _Miniconda3: https://docs.conda.io/projects/miniconda/en/latest/
-.. _YAML environment file: https://github.com/EATRIS/motbx/blob/main/envs/motbxtools.yml
+.. _YAML environment file: https://github.com/EATRIS/motbx/blob/main/envs/motbxtools_notebooks.yml
 .. _notebooks: https://github.com/EATRIS/motbx/tree/main/notebooks
 .. _Jupyter notebooks: https://github.com/EATRIS/motbx/tree/main/notebooks
diff --git a/doc/modules.rst b/doc/modules.rst
@@ -1,7 +1,7 @@
-`MOTBXtools` Python package
+`motbxtools` Python package
 ===========================
 
-The `MOTBXtools` package provides classes and methods to read, write, validate,
+The `motbxtools` package provides classes and methods to read, write, validate,
 or summarise MOTBX resources. It is available in the directory `src/motbxtools`_.
 
 
@@ -14,9 +14,9 @@ Module `motbxschema`
 
 
 Unit testing
-~~~~~~~~~~~~
+------------
 
-The directory `tests/test_motbxtools`_ contains unit tests for the `MOTBXtools` package.
+The directory `tests/test_motbxtools`_ contains unit tests for the `motbxtools` package.
 The `tests`_ directory additionally contains MOTBX resource `YAML` files used by the tests.
 Unit tests can be run using the GitHub action defined in `.github/workflows/tests.yml`_ via `actions`_.
 

diff --git a/doc/utilities.rst b/doc/utilities.rst
@@ -0,0 +1,18 @@
+Scripts and GitHub Actions
+==========================
+
+Scripts for executing specific tasks are available in the `motbxtools.utils`_
+module. They can be run locally, or as automated GitHub Actions.
+
+Script `utils.summarise_resources`
+----------------------------------
+
+.. argparse::
+    :module: utils.summarise_resources
+    :func: parser
+    :prog: summarise_resources
+
+This script can be executed as GitHub Action `create_summary`_.
+
+.. _motbxtools.utils: https://github.com/EATRIS/motbx/tree/main/src/motbxtools/utils
+.. _create_summary: https://github.com/EATRIS/motbx/actions/workflows/create_summary.yml
diff --git a/envs/motbxtest_and_doc.yml → envs/motbxtools_doc.yml b/envs/motbxtest_and_doc.yml → envs/motbxtools_doc.yml
@@ -1,4 +1,4 @@
-name: motbxtest_and_doc
+name: motbxtools_doc
 channels:
   - conda-forge
   - defaults
@@ -7,8 +7,8 @@ dependencies:
   - jsonschema=4.17.3
   - pip=23.2.1
   - python=3.11.4
-  - pytest
   - pyyaml=6.0
   - requests=2.27.1
   - sphinx=7.0.0
+  - sphinx-argparse=0.4.0
   - validators=0.20.0
diff --git a/envs/motbxtools.yml → envs/motbxtools_notebooks.yml b/envs/motbxtools.yml → envs/motbxtools_notebooks.yml
@@ -1,4 +1,4 @@
-name: motbxtools
+name: motbxtools_notebooks
 channels:
   - anaconda
   - conda-forge

diff --git a/envs/motbxtools_test.yml b/envs/motbxtools_test.yml
@@ -0,0 +1,12 @@
+name: motbxtools_test
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - jsonschema=4.17.3
+  - pip=23.2.1
+  - python=3.11.4
+  - pytest
+  - pyyaml=6.0
+  - requests=2.27.1
+  - validators=0.20.0
diff --git a/src/motbxtools/utils/summarise_resources.py b/src/motbxtools/utils/summarise_resources.py
@@ -19,25 +19,31 @@
 SUMMARY_DIR = MOTBX_DIR.joinpath("resources/summary")
 
 
-def main():
-    parser = argparse.ArgumentParser(usage=__doc__)
-    parser.add_argument(
-        'version',
-        type=str,
-        help="The version of the MOTBX resources summary.")
-    args = parser.parse_args()
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter)
+parser.add_argument(
+    'version',
+    type=str,
+    default='latest',
+    help="""The version of the MOTBX resources summary.
+    DEFAULT: retrieve latest version from 'resources/MOTBX_version.yaml'.
+    ALTERNATIVE: specify a new version; this will update the latest version
+    specified in 'resources/MOTBX_version.yaml'.""")
+
 
-    print("Received input 'version':", args.version)
+def main(version):
+    print("Received input 'version':", version)
     with VERSION_FILE.open(mode="r", encoding="utf-8") as f:
         motbx_versions = yaml.safe_load(f)
     # get latest version based on input parameter 'version'
-    if args.version == "latest":
+    if version == "latest":
         latest_version = motbx_versions["latest"]
         print("Updating latest version:", latest_version)
     else:
         with VERSION_FILE.open(mode="w", encoding="utf-8") as f:
             motbx_versions["previous"].insert(0, motbx_versions["latest"])
-            latest_version = motbx_versions["latest"] = args.version
+            latest_version = motbx_versions["latest"] = version
             yaml.dump(motbx_versions, f)
             print("Creating new version:", latest_version)
     # get previous version
@@ -68,4 +74,5 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    args = parser.parse_args()
+    main(args.version)