YAML templates docs are dependent on `sphinx-apidoc`
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 35/100
- issue の種類
- ドキュメント
- 明瞭さ
- 説明が足りない
- 活発さ
- 停滞
- 技術スタック
- python
調査の方向性
docs/sphinx-build.sh と docs/source/api 配下の生成ファイル、特に methods_database.rst と scripts.rst から始めます。YAML テンプレートのドキュメント用に sphinx-apidoc の出力がどのように変更されているかを追跡し、その後、警告を再現するためにドキュメント化されている sphinx-build コマンドを実行します。YAML テンプレートのドキュメントが引き続きビルドされ、未使用の API ファイルと import 警告が削除されていれば完了です。
索引モデルが issue の本文から書いたものです。
説明
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
- 主要言語
- Python
- スター
- 0
- フォーク
- 1
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
DiamondLightSource/httomo-backends のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
-
documentation question
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
DiamondLightSource/httomo-backends#10 · コメント 2 件 ·
-
documentation question
難易度 2/5 1〜3時間 初心者へのやさしさ 35/100
-
documentation
難易度 1/5 1時間未満 初心者へのやさしさ 45/100
DiamondLightSource/httomo-backends の issue をすべて見る
似ている issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
aws-samples/sample-per-model-bedrock#261 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
pwncollege/dojo#1188 ·
メンテナーはふだん 1 日以内に返信
-
bug launcher packaging
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
tenstorrent/tt-studio#1426 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
python-attrs/cattrs#796 ·
メンテナーはふだん 1 日以内に返信