Docs Warning Triage

Docs Warning Triage#

This page tracks known Sphinx warning classes so documentation review can focus on meaningful regressions instead of rediscovering existing noise.

Local Check#

uv run python -m sphinx -b html docs /private/tmp/deeptb-docs-check

Warning Classes#

Warning class

Current policy

Missing toctree entries

Fix low-risk documentation pages when they are already part of the public docs. Keep design notes unlisted unless they are ready for public navigation.

Image path warnings

Fix direct path mistakes. Prefer paths that resolve from the Markdown file location.

Markdown heading warnings

Fix obvious cases where a Markdown document starts at ## instead of #.

Code block highlighting warnings

Track only for now. Many examples contain JSON-like snippets with comments or ellipses; fixing them requires broader historical docs cleanup.

Notebook execution or output warnings

Track only for now. Do not change notebook contents or execution policy in maintenance-only PRs.

Third-party Sphinx deprecation warnings

Track only for now unless they break the build.

Fixed In This Maintenance Pass#

  • Added low-risk public pages to toctrees for electronic properties, community docs, and quick examples.

  • Fixed the smoothing-function image path in docs/advanced/sktb/dptb_env.md.

  • Converted docs/pardiso_architecture.md to start with a real H1 Markdown heading.

Last Observed Full Build#

Command:

uv run python -m sphinx -b html docs /private/tmp/deeptb-docs-check

Latest maintenance validation succeeded with 41 warnings. The warnings are still in the tracked classes above:

  • missing _static directory from html_static_path;

  • notebook execution failures for quick-start notebooks, with tracebacks written under the build reports/ directory;

  • unlisted design/status notes: docs/pardiso_architecture.md and docs/phase1_summary.md;

  • definition-list formatting in docs/input_params/run_options.rst;

  • historical code block highlighting warnings from JSON-like snippets with comments, ellipses, tree glyphs, traceback text, or non-ASCII math symbols;

  • missing MyST cross references in docs/phase1_summary.md and docs/quick_start/hands_on/tutorial4_E3_si.ipynb;

  • deepmodeling_sphinx deprecation warnings for Sphinx 9 APIs.

This maintenance pass does not attempt to execute or repair notebooks, rewrite historical code snippets, or promote design/status notes into public navigation.

Known Warnings Left For Later#

  • Code block highlighting warnings in historical docs that use JSON-like examples with comments or ellipses.

  • Notebook execution or notebook output warnings.

  • Unlisted design/status notes such as docs/phase1_summary.md.

  • Sphinx/deepmodeling_sphinx deprecation or static-copy warnings that do not fail the build.