Merge branch 'update_doc' into 'main'

Doc: generate application help from `program-output`

See merge request !293

doc/conf.py

@@ -42,6 +42,7 @@ extensions = [
     "nbsphinx",
     "sphinx_design",
     "sphinx_autodoc_typehints",
+    "sphinxcontrib.programoutput",
 ]
 
 # Add any paths that contain custom static files (such as style sheets) here,

doc/tutorials/copynx.rst

@@ -47,3 +47,8 @@ Virtual dataset behavior
 If the source file contains HDF5 virtual dataset then the virtual source will be updated to fix relative links.
 
 You can also use the 'remove-vds' option. In this case the HDF5 - virtual dataset will be replaced by a standard HDF5 dataset (getting rid of the virtual link). But be aware that with this option full dataaset must be able to fill in memory in order to modify it (at least for now).
+
+Help
+----
+
+.. program-output:: nxtomomill nx-copy --help

doc/tutorials/dxfile2nx.rst

@@ -17,50 +17,8 @@ To call this application you can call directly
 
 You can access help by calling
 
-.. code-block:: bash
+.. program-output:: nxtomomill dxfile2nx --help
 
-    $ nxtomomill dxfile2nx --help
-    usage: nxtomomill dxfile2nx [-h] [--input_entry INPUT_ENTRY]
-                                [--output_entry OUTPUT_ENTRY]
-                                [--file_extension FILE_EXTENSION]
-                                [--scan-range SCAN_RANGE]
-                                [--pixel-size PIXEL_SIZE] [--fov FIELD_OF_VIEW]
-                                [--distance DISTANCE] [--energy ENERGY]
-                                [--overwrite] [--no-data-copy]
-                                input_file output_file
-
-    convert acquisition contained in provided dx file to NXTomo entry
-
-    positional arguments:
-      input_file            master file of the acquisition
-      output_file           output .nx or .h5 file
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      --input_entry INPUT_ENTRY
-                            h5py group path to be converted
-      --output_entry OUTPUT_ENTRY
-                            h5py group path to store the NXTomo
-      --file_extension FILE_EXTENSION
-                            extension of the output file. Valid values are
-                            .h5/.hdf5/.nx
-      --scan-range SCAN_RANGE
-                            scan range of the projections. Dark and flat will
-                            always be considered with rotation angle ==
-                            scan_range[0]
-      --pixel-size PIXEL_SIZE
-                            pixel size in meter as (x pixel size, y pixel size)
-      --fov FIELD_OF_VIEW, --field-of-view FIELD_OF_VIEW
-                            pixel size in meter as (x pixel size, y pixel size)
-      --distance DISTANCE, --detector-sample-distance DISTANCE
-                            sample to detector distance (in meter)
-      --energy ENERGY, --incident-beam-energy ENERGY
-                            incident beam energy in keV
-      --overwrite           Do not ask for user permission to overwrite output
-                            files
-      --no-data-copy        Avoid creating any symbolic link between input and
-                            output fileand duplicate the frame datasets to have a
-                            'all-in-one' output file.
 
 Here is an example on how to convert a dxfile.
 For it we downloaded the `tomo_00068 dataset <https://tomobank.readthedocs.io/en/latest/source/data/docs.data.phasecontrast.html#wet-sample>`_

doc/tutorials/edf2nx.rst

@@ -112,3 +112,9 @@ Once your configuration is edited you can use it from the `nxtomomill edf2nx` us
 .. note:: to ease usage the "dataset basename" and the "info file" can also be provided from command line (`--dataset-basename` and `--info-file` options).
           If you provide one of those parameters from the command line option then it should not be provided from the configuration.
           This is the same for `scan_path` aka folder path (containing raw data / .edf) and `output_file`
+
+
+Help
+----
+
+.. program-output:: nxtomomill edf2nx --help

doc/tutorials/h52nx.rst

@@ -104,77 +104,7 @@ other (rotation angle, translation...)
 Most of the key used to retrieve other operation can be overwrite from
 an option from command line
 
-.. code-block:: console
-
-  $ nxtomomill h52nx --help
-  convert data acquired as hdf5 from bliss to nexus `NXtomo` classes. For
-  `zseries` it will create one entry per `z`
-
-  positional arguments:
-    input_file            master file of the acquisition
-    output_file           output .nx or .h5 file
-
-  optional arguments:
-    -h, --help            show this help message and exit
-    --file_extension FILE_EXTENSION
-                          extension of the output file. Valid values are
-                          .h5/.hdf5/.nx
-    --single-file         merge all scan sequence to the same output file. By
-                          default create one file per sequence and group all
-                          sequence in the output file
-    --overwrite           Do not ask for user permission to overwrite output
-                          files
-    --debug               Set logs to debug mode
-    --entries ENTRIES     Specify (root) entries to be converted. By default it
-                          will try to convert all existing entries.
-    --ignore-sub-entries IGNORE_SUB_ENTRIES
-                          Specify (none-root) sub entries to ignore.
-    --raises-error        Raise errors if some data are not met instead of
-                          providing some default values
-    --no-input, --no-input-for-missing-information
-                          The user won't be ask for any inputs
-    --standard-format     Format of the input file is the 'standard' tomography
-                          format
-    --sample_x_keys SAMPLE_X_KEYS, --sample-u-keys SAMPLE_X_KEYS
-                          sample x translation key in bliss HDF5 file (direction is independent of the rotation angle)
-    --sample_y_keys SAMPLE_Y_KEYS, --sample-y-keys SAMPLE_Y_KEYS
-                          sample y translation key in bliss HDF5 file (direction is independent of the rotation angle)
-    --translation_z_keys TRANSLATION_Z_KEYS, --translation-z-keys TRANSLATION_Z_KEYS
-                          z translation key in bliss HDF5 file
-    --valid_camera_names VALID_CAMERA_NAMES, --valid-camera-names VALID_CAMERA_NAMES
-                          Valid NXDetector dataset name to be considered.
-                          Otherwise will try to deduce them from NX_class
-                          attribute (value should beNXdetector) or from
-                          instrument group child structure.
-    --rot_angle_keys ROT_ANGLE_KEYS, --rot-angle-keys ROT_ANGLE_KEYS
-                          Valid dataset name for rotation angle
-    --acq_expo_time_keys ACQ_EXPO_TIME_KEYS, --acq-expo-time-keys ACQ_EXPO_TIME_KEYS
-                          Valid dataset name for acquisition exposure time
-    --x_pixel_size_key X_PIXEL_SIZE_KEY, --x-pixel-size-key X_PIXEL_SIZE_KEY
-                          X pixel size key to read
-    --y_pixel_size_key Y_PIXEL_SIZE_KEY, --y-pixel-size-key Y_PIXEL_SIZE_KEY
-                          Y pixel size key to read
-    --init_titles INIT_TITLES, --init-titles INIT_TITLES
-                          Titles corresponding to init scans
-    --init_zserie_titles INIT_ZSERIE_TITLES, --init-zserie-titles INIT_ZSERIE_TITLES
-                          Titles corresponding to zserie init scans
-    --dark_titles DARK_TITLES, --dark-titles DARK_TITLES
-                          Titles corresponding to dark scans
-    --flat_titles --flat_titles --ref_titles FLAT_TITLES, --ref-titles FLAT_TITLES
-                          Titles corresponding to ref scans
-    --proj_titles PROJ_TITLES, --proj-titles PROJ_TITLES
-                          Titles corresponding to projection scans
-    --align_titles ALIGN_TITLES, --align-titles ALIGN_TITLES
-                          Titles corresponding to alignment scans
-    --set-params [SET_PARAMS [SET_PARAMS ...]]
-                          Allow manual definition of some parameters. Valid
-                          parameters (and expected input unit) are: energy
-                          (kev), x_pixel_size (m), y_pixel_size (m). Should be
-                          added at the end of the command line because will try
-                          to cover all text set after this option.
-    --config CONFIG, --config-file CONFIG, --configuration CONFIG, --configuration-file CONFIG
-                          file containing the full configuration to convert from
-                          h5 bliss to nexus
+.. program-output:: nxtomomill h52nx --help
 
 .. _h52nx_with_config_file:
 

doc/tutorials/patch_nx.rst

@@ -136,3 +136,8 @@ This is one way to proceed to replace flat field frames:
         It will also try to link it with the full dataset at `/entry000B/instrument/detector/data`
 
 7. check that your dataset is complete (using silx view for example)
+
+Help
+----
+
+.. program-output:: nxtomomill patch-nx --help

pyproject.toml

@@ -66,7 +66,8 @@ doc = [
     "h5glance",
     "pydata_sphinx_theme",
     "sphinx-design",
-    "sphinx-autodoc-typehints"
+    "sphinx-autodoc-typehints",
+    "sphinxcontrib-programoutput",
 ]
 
 [build-system]