Skip to content

Commit

Permalink
Merge pull request #411 from FAIRmat-NFDI/docs-for-cli-api
Browse files Browse the repository at this point in the history
Add docs for CLI API, tool to report installed readers
  • Loading branch information
lukaspie authored Aug 26, 2024
2 parents 6bf0bc5 + faa3c07 commit 2d678b5
Show file tree
Hide file tree
Showing 7 changed files with 72 additions and 15 deletions.
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
10 changes: 8 additions & 2 deletions docs/how-tos/build-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 3 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
40 changes: 40 additions & 0 deletions docs/reference/cli-api.md
Original file line number Diff line number Diff line change
@@ -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
4 changes: 1 addition & 3 deletions mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -31,9 +32,6 @@ plugins:
- macros:
module_name: src/pynxtools/mkdocs

hooks:
- scripts/generate_dataconverter_help.py

theme:
name: material
palette:
Expand Down
13 changes: 12 additions & 1 deletion src/pynxtools/dataconverter/convert.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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}.")
16 changes: 8 additions & 8 deletions src/pynxtools/nexus/nexus.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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(
Expand All @@ -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)
Expand Down

0 comments on commit 2d678b5

Please sign in to comment.