From 43ddb6bb7e0c07286af98e7534e51596503f398c Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 23 Aug 2024 16:58:17 +0200 Subject: [PATCH 1/4] add docs for CLI API --- .gitignore | 1 - docs/how-tos/build-a-plugin.md | 10 +++++-- docs/index.md | 3 ++ docs/reference/cli-api.md | 40 ++++++++++++++++++++++++++ mkdocs.yaml | 8 ++++-- src/pynxtools/dataconverter/convert.py | 6 +++- src/pynxtools/nexus/nexus.py | 16 +++++------ 7 files changed, 69 insertions(+), 15 deletions(-) create mode 100644 docs/reference/cli-api.md diff --git a/.gitignore b/.gitignore index 42abff368..bd139eea0 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/how-tos/build-a-plugin.md b/docs/how-tos/build-a-plugin.md index 38673a451..9f4f6b1e0 100644 --- a/docs/how-tos/build-a-plugin.md +++ b/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!} \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d74e51f5f..13b494e5c 100644 --- a/docs/index.md +++ b/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, among others, convert data and verify NeXus file. 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. diff --git a/docs/reference/cli-api.md b/docs/reference/cli-api.md new file mode 100644 index 000000000..b87c5c744 --- /dev/null +++ b/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.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 \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index ce7c98463..a7f52ccdd 100644 --- a/mkdocs.yaml +++ b/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: @@ -76,6 +74,10 @@ markdown_extensions: extra: generator: false homepage: https://nomad-lab.eu + click: + show_subcommands: true + show_options: true + show_help: true use_directory_urls: false diff --git a/src/pynxtools/dataconverter/convert.py b/src/pynxtools/dataconverter/convert.py index c01706ae2..4dc40c011 100644 --- a/src/pynxtools/dataconverter/convert.py +++ b/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 diff --git a/src/pynxtools/nexus/nexus.py b/src/pynxtools/nexus/nexus.py index ef6328fc0..7dcefa717 100644 --- a/src/pynxtools/nexus/nexus.py +++ b/src/pynxtools/nexus/nexus.py @@ -783,10 +783,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", @@ -795,7 +792,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( @@ -805,12 +802,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) From 460b56124b74f8824ad27516dc5111928e256c50 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 23 Aug 2024 17:07:52 +0200 Subject: [PATCH 2/4] add cli sub-command to support installed readers --- src/pynxtools/dataconverter/convert.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/pynxtools/dataconverter/convert.py b/src/pynxtools/dataconverter/convert.py index 4dc40c011..1e3d4be7e 100644 --- a/src/pynxtools/dataconverter/convert.py +++ b/src/pynxtools/dataconverter/convert.py @@ -467,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}.") From 6ae22eeaadf23b0443cf987e1c04b9c48c523a1a Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 23 Aug 2024 17:10:39 +0200 Subject: [PATCH 3/4] clean up mkdocs.yaml --- mkdocs.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/mkdocs.yaml b/mkdocs.yaml index a7f52ccdd..7eaa9ebd9 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -74,10 +74,6 @@ markdown_extensions: extra: generator: false homepage: https://nomad-lab.eu - click: - show_subcommands: true - show_options: true - show_help: true use_directory_urls: false From faa3c07497f8524306c7538a897980bf98178d4a Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 26 Aug 2024 09:27:56 +0200 Subject: [PATCH 4/4] small updates to keep things clean --- docs/index.md | 2 +- src/pynxtools/dataconverter/convert.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 13b494e5c..af4e86888 100644 --- a/docs/index.md +++ b/docs/index.md @@ -55,7 +55,7 @@ An introduction to NeXus and its design principles. ### Reference -`pynxtools` has a number of command line tools that can be used to, among others, convert data and verify NeXus file. You can more information about the +`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). diff --git a/src/pynxtools/dataconverter/convert.py b/src/pynxtools/dataconverter/convert.py index 1e3d4be7e..a38392669 100644 --- a/src/pynxtools/dataconverter/convert.py +++ b/src/pynxtools/dataconverter/convert.py @@ -471,6 +471,6 @@ def write_to_file(text): @main_cli.command("get-readers") def get_reader_cli(): - "Prints a list of all installed readers." + """Prints a list of all installed readers.""" readers = get_names_of_all_readers() logger.info(f"The following readers are currently installed: {readers}.")