Merge pull request #411 from FAIRmat-NFDI/docs-for-cli-api

Add docs for CLI API, tool to report installed readers

Author: lukaspie

.gitignore

@@ -202,7 +202,6 @@ cython_debug/
 !dev-requirements.txt
 !mkdocs-requirements.txt
 !src/pynxtools/nexus-version.txt
-docs/how-tos/dataconverter_help_output.md
 build/
 nexusparser.egg-info/PKG-INFO
 .python-version

docs/how-tos/build-a-plugin.md

@@ -155,5 +155,11 @@ user@box:~$ dataconverter --reader mydatareader --nxdl NXmynxdl --output path_to
 Here, the ``--reader`` flag must match the reader name defined in `[project.entry-points."pynxtools.reader"]` in the pyproject.toml file. The NXDL name passed to ``--nxdl``must be a valid NeXus NXDL/XML file in `pynxtools.definitions`.
 
 Aside from this default structure, there are many more flags that can be passed to the
-dataconverter call. Here is an output of its ```help``` call:
-{!how-tos/dataconverter_help_output.md!}
+dataconverter call. Here is its API:
+::: mkdocs-click
+    :module: pynxtools.dataconverter.convert
+    :command: convert_cli
+    :prog_name: dataconverter
+    :depth: 2
+    :style: table
+    :list_subcommands: True

docs/index.md

@@ -55,6 +55,9 @@ An introduction to NeXus and its design principles.
 
 ### Reference
 
+`pynxtools` has a number of command line tools that can be used to convert data and verify NeXus files. You can more information about the
+API [here](reference/cli-api.md).
+
 Within FAIRmat, we maintain a number of reader plugins for different experimental techniques. You can find more information [here](reference/plugins.md).
 
 [Here](reference/definitions.md), you find the detailed list of application definitions and base classes and their respective fields.

docs/reference/cli-api.md

@@ -0,0 +1,40 @@
+# API for command line tools
+
+`pynxtools` supports a number of command line applications. This page provides documentation for their current API.
+
+## Data conversion
+Note that simply calling `dataconverter` defaults to `dataconverter convert`.
+
+::: mkdocs-click
+    :module: pynxtools.dataconverter.convert
+    :command: main_cli
+    :prog_name: dataconverter
+    :depth: 2
+    :style: table
+    :list_subcommands: True
+
+## NeXus file verification
+<!-- ::: mkdocs-click
+    :module: "pynxtools.dataconverter.verify
+    :command: verify_nexus
+    :prog_name: verify_nexus
+    :depth: 1
+    :style: table
+    :list_subcommands: True -->
+
+::: mkdocs-click
+    :module: pynxtools.nexus.nexus
+    :command: main
+    :prog_name: read_nexus
+    :depth: 2
+    :style: table
+    :list_subcommands: True
+
+## ELN generation
+::: mkdocs-click
+    :module: pynxtools.eln_mapper.eln_mapper
+    :command: get_eln
+    :prog_name: generate_eln
+    :depth: 1
+    :style: table
+    :list_subcommands: True

mkdocs.yaml

@@ -23,6 +23,7 @@ nav:
     - learn/multiple-appdefs.md
     - learn/multi-format-reader.md
   - Reference:
+    - reference/cli-api.md
     - reference/plugins.md
     - reference/definitions.md
 
@@ -31,9 +32,6 @@ plugins:
   - macros:
       module_name: src/pynxtools/mkdocs
 
-hooks:
-  - scripts/generate_dataconverter_help.py
-
 theme:
   name: material
   palette:

src/pynxtools/dataconverter/convert.py

@@ -272,7 +272,11 @@ def format_options(
             )
 
 
-@click.group(cls=CustomClickGroup, default="convert", default_if_no_args=True)
+@click.group(
+    cls=CustomClickGroup,
+    default="convert",
+    default_if_no_args=True,
+)
 def main_cli():
     pass
 
@@ -463,3 +467,10 @@ def write_to_file(text):
             ensure_ascii=False,
         )
     )
+
+
+@main_cli.command("get-readers")
+def get_reader_cli():
+    """Prints a list of all installed readers."""
+    readers = get_names_of_all_readers()
+    logger.info(f"The following readers are currently installed: {readers}.")

src/pynxtools/nexus/nexus.py

@@ -794,10 +794,7 @@ def process_nexus_master_file(self, parser):
     "--nexus-file",
     required=False,
     default=None,
-    help=(
-        "NeXus file with extension .nxs to learn NeXus different concept"
-        " documentation and concept."
-    ),
+    help=("NeXus file with extension .nxs."),
 )
 @click.option(
     "-d",
@@ -806,7 +803,7 @@ def process_nexus_master_file(self, parser):
     default=None,
     help=(
         "Definition path in nexus output (.nxs) file. Returns debug"
-        "log relavent with that definition path. Example: /entry/data/delays"
+        " log relevant with that definition path. Example: /entry/data/delays"
     ),
 )
 @click.option(
@@ -816,12 +813,15 @@ def process_nexus_master_file(self, parser):
     default=None,
     help=(
         "Concept path from application definition file (.nxdl,xml). Finds out"
-        "all the available concept definition (IS-A realation) for rendered"
-        "concept path. Example: /NXarpes/ENTRY/INSTRUMENT/analyser"
+        " all the available concept definition (IS-A realation) for rendered"
+        " concept path. Example: /NXarpes/ENTRY/INSTRUMENT/analyser"
     ),
 )
 def main(nexus_file, documentation, concept):
-    """The main function to call when used as a script."""
+    """
+    Functionality to extract documentation and concept definition
+    information about the individual parts of a NeXus/HDF5 file."""
+
     logging_format = "%(levelname)s: %(message)s"
     stdout_handler = logging.StreamHandler(sys.stdout)
     stdout_handler.setLevel(logging.DEBUG)