Skip to content

YAML templates docs are dependent on sphinx-apidoc #12

@yousefmoazzam

Description

@yousefmoazzam

As noted in #10 (comment), the YAML templates docs are dependent on sphinx-apidoc. More specifically, the rst files generated by sphinx-apidoc (which is a tool for generating API docs) are modified after sphinx-apidoc runs, in order to produce the YAML templates docs.

This approach works decently, but one downside is that API docs are being generated for everything in httomo_backends/ (none fo which are python packages or modules, there's only some standalone scripts), and so when the final sphinx-build command is run in sphinx-build.sh, there are some unused API docs rst files that causes some warnings to be outputted:

Running Sphinx v8.1.3
loading translations [en]... done
[autosummary] generating autosummary for: api/httomolib.misc.images.rst, api/httomolib.misc.morph.rst, api/httomolib.misc.segm.rst, api/httomolib.prep.phase.rst, api/httomolibgpu.misc.corr.rst, api/httomolibgpu.misc.morph.rst, api/httomolibgpu.misc.rescale.rst, api/httomolibgpu.prep.alignment.rst, api/httomolibgpu.prep.normalize.rst, api/httomolibgpu.prep.phase.rst, ..., api/tomopy.prep.alignment.rst, api/tomopy.prep.normalize.rst, api/tomopy.prep.phase.rst, api/tomopy.prep.stripe.rst, api/tomopy.recon.algorithm.rst, api/tomopy.recon.rotation.rst, api/tomopy.sim.project.rst, backends/templates.rst, index.rst, utilities/yaml_generator.rst
WARNING: Failed to import methods_database.
Possible hints:
* KeyError: 'methods_database'
* ModuleNotFoundError: No module named 'methods_database'
WARNING: Failed to import scripts.yaml_templates_generator.
Possible hints:
* KeyError: 'scripts'
* ModuleNotFoundError: No module named 'scripts'
WARNING: Failed to import scripts.yaml_unsupported_tomopy_remove.
Possible hints:
* KeyError: 'scripts'
* ModuleNotFoundError: No module named 'scripts'
WARNING: Failed to import scripts.
Possible hints:
* KeyError: 'scripts'
* ModuleNotFoundError: No module named 'scripts'
Writing evaluated template result to /dls/science/users/twi18192/httomo-backends/docs/build/_static/nbsphinx-code-cells.css
building [mo]: all of 0 po files
writing output...
building [html]: all source files
updating environment: [new config] 29 added, 0 changed, 0 removed
reading sources... [100%] utilities/yaml_generator
WARNING: autodoc: failed to import module 'methods_database'; the following exception was raised:
No module named 'methods_database' [autodoc.import_object]
WARNING: autodoc: failed to import module 'scripts'; the following exception was raised:
No module named 'scripts' [autodoc.import_object]
WARNING: autodoc: failed to import module 'yaml_templates_generator' from module 'scripts'; the following exception was raised:
No module named 'scripts' [autodoc.import_object]
/dls/science/users/twi18192/httomo-backends/docs/source/api/scripts.yaml_unsupported_tomopy_remove.rst:2: WARNING: Title underline too short.

:mod:`scripts.yaml_unsupported_tomopy_remove`
============================================ [docutils]
WARNING: autodoc: failed to import module 'yaml_unsupported_tomopy_remove' from module 'scripts'; the following exception was raised:
No module named 'scripts' [autodoc.import_object]
looking for now-outdated files... none found
pickling environment... done
checking consistency... /dls/science/users/twi18192/httomo-backends/docs/source/api/methods_database.rst: WARNING: document isn't included in any toctree
/dls/science/users/twi18192/httomo-backends/docs/source/api/scripts.rst: WARNING: document isn't included in any toctree
done

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions