YAML templates docs are dependent on `sphinx-apidoc`
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Start with docs/sphinx-build.sh and the generated files under docs/source/api, especially methods_database.rst and scripts.rst. Trace how sphinx-apidoc output is modified for the YAML templates docs, then run the documented sphinx-build command to reproduce the warnings. Done means the YAML templates documentation still builds and the unused API files and import warnings are removed.
Written by the indexing model from the issue text.
Description
As noted in https://github.com/DiamondLightSource/httomo-backends/issues/10#issuecomment-2443698342, 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
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from DiamondLightSource/httomo-backends
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
documentation question
Difficulty 5/5 Over a week Newbie friendliness 25/100
DiamondLightSource/httomo-backends#10 · 2 comments ·
-
documentation question
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
-
documentation
Difficulty 1/5 Under an hour Newbie friendliness 45/100
All issues in DiamondLightSource/httomo-backends
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
EchoTools/nevr-runtime#651 ·
Maintainers usually reply within 1 day
-
bug frontend rt sev-3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
noontide-co/mainbranch#1211 · 1 comment ·
Maintainers usually reply within 1 day
-
[1.x Bug] run-operation --sql reports success but rolls back writes on transaction-capable adaptersOpentriage
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
dbt-labs/dbt#16784 · 1 comment ·
Maintainers usually reply within 1 day