ReadTheDocsにpublishするための準備

[yuji38kwmt]

#110 がマージされてから対応する。

対応したこと

• ReadTheDcos用のライブラリバージョンをアップデート
• command_sample.mdを分割する。すべてのコマンドが1つのファイルにまとまっていて、探しにくかったため。

ソース以外で対応したこと

• ReadTheDocsのプロジェクトを作成
• GitHub Settingsでwebhookの設定

プルリクがマージされてからやること

• コマンドサンプルの使用例が古いものを修正する
• コマンドサンプルを適切に改行して見やすくする

ドキュメント生成時の警告

• UserWarning: Container node skipped: type=document：この警告の意味が分からなかった
• WARNING: document isn't included in any toctree：restructedTextのToC機能を使っていないため。将来的にmarkdownからrestructedTextに移行した方がよいかもしれない。

$ make docs
cd docs && poetry run make html
make[1]: Entering directory '/workspaces/annofab-3dpc-editor-cli/docs'
Running Sphinx v5.2.3
loading translations [ja]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 13 source files that are out of date
updating environment: [new config] 13 added, 0 changed, 0 removed
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))
/workspaces/annofab-3dpc-editor-cli/.venv/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
  warn("Container node skipped: type={0}".format(mdnode.t))

looking for now-outdated files... none found
pickling environment... done
checking consistency... /workspaces/annofab-3dpc-editor-cli/docs/user_guide/annofab_point_cloud_format.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/create_project.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/make_kitti_data.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/make_scene.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/set_annotation_area.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/set_label.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/set_preset_cuboid_size.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_kitti_data.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_scene.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_scene_to_s3.md: WARNING: document isn't included in any toctree
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/kitti_3d_object_detection.md: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] user_guide/kitti_3d_object_detection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_kitti_data.md:3: WARNING: None:any reference target not found: kitti_3d_object_detection
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_scene.md:3: WARNING: None:any reference target not found: annofab_point_cloud_format
/workspaces/annofab-3dpc-editor-cli/docs/user_guide/command_sample/upload_scene_to_s3.md:3: WARNING: None:any reference target not found: annofab_point_cloud_format
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja)... done
dumping object inventory... done
build succeeded, 15 warnings.

The HTML pages are in _build/html.
make[1]: Leaving directory '/workspaces/annofab-3dpc-editor-cli/docs'

[yuji38kwmt]

_staticディレクトリを追加したのは、make docsコマンド実行時に以下のWARNINGが発生したため。
docs/conf.pyで_staticディレクトリを参照していたのに、そのディレクトリが存在しなかった。

vscode@example:/workspaces/annofab-3dpc-editor-cli$ make docs
cd docs && poetry run make html
make[1]: Entering directory '/workspaces/annofab-3dpc-editor-cli/docs'
Running Sphinx v5.2.3
loading translations [ja]... done
WARNING: html_static_path entry '_static' does not exist

[yuji38kwmt]

poetry.lockと同じバージョンにした。

[seraphr]

UserWarning: Container node skipped: type=document：この警告の意味が分からなかった

readthedocs/recommonmark#177 ぽいですねぇ
ただ、recommonmarkはdeprecatedになっていてので、MyST-parserに移行しろということになっている
SphinxでMarkdown拡張言語のMySTを扱うとかがググると出てきますな。

WARNING: document isn't included in any toctree：restructedTextのToC機能を使っていないため。将来的にmarkdownからrestructedTextに移行した方がよいかもしれない。

別にmarkdownのまま、目次出力するなり、目次が要らないなら警告除去するなり出来るのでは？

[yuji38kwmt]

MyST-parserに移行しろということになっている
MyST-parserに移行しました。

グローバルヘッダメニュの見出しを消しても良い気がするけど、消し方が分かりませんでした。