Skip to content

README.md

Latest commit

 

History

History
71 lines (59 loc) · 3.45 KB

README.md

File metadata and controls

71 lines (59 loc) · 3.45 KB
Raw

Documentation source and maintenance

This directory is the source for the bilingual fincore_cpp documentation site. It is built with Doxygen -> XML -> Breathe -> Sphinx. English is the authoritative source; locale/zh_CN/LC_MESSAGES/*.po contains the reviewed Simplified Chinese catalog. Generated XML, HTML, gettext templates and .mo files stay under docs/_build/ and are not committed.

Build locally

python -m venv .venv-docs
.venv-docs/bin/pip install -r docs/requirements-docs.txt
cd docs/site
doxygen Doxyfile
python tools/normalize_doxygen_xml.py ../_build/doxygen/xml
sphinx-build -b gettext -W --keep-going . ../_build/gettext
sphinx-intl update -p ../_build/gettext -l zh_CN
sphinx-build -b html -W -n --keep-going . ../_build/html/en
FINCORE_DOCS_LANGUAGE=zh_CN sphinx-build -b html -W -n --keep-going . ../_build/html/zh_CN

Pass -E when the Doxygen XML changed since the last build: reused doctrees keep the previous C++ domain symbols, and resolving a reference against them aborts inside sphinx.domains.cpp instead of reporting a warning.

After both languages are built, run python docs/site/tools/check_built_site.py from the repository root. It walks the built pages for internal links that do not resolve and for absolute machine paths, and reports the catalog counts, exiting non-zero on any of them.

Windows uses .venv-docs\Scripts\pip.exe, sphinx-build.exe and sphinx-intl.exe; the same source paths apply. The verified toolchain is pinned in docs/requirements-docs.txt and docs/requirements-docs.lock.txt. Doxygen 1.9.7 is the local baseline; CI installs the distribution package.

Page and coverage rules

  • Public API coverage is tracked by api-ledger.tsv and api-ledger-summary.json, generated by tools/build_api_ledger.py from the Doxygen XML. Run the generator after changing public headers.
  • tools/check_comment_only.py verifies that a header diff changes only comments (token comparison against HEAD).
  • Do not start a section heading with a number (## 1. Build ...). MyST parses that shape in a way that leaves the heading untranslated even when the catalog entry exists; write ## Build ... instead.
  • The English source and Chinese translations must keep the same page list. Update .po files when English prose changes; an empty, fuzzy or stale translation is not counted as bilingual coverage.
  • api/index.md is the API entry. Expand module pages only after the corresponding comment round has passed Doxygen and strict Sphinx checks.

Publication

GitHub Pages is configured by .github/workflows/docs.yml and deploys from successful dev/master builds. Read the Docs uses .readthedocs.yaml; one RTD project (fincore_cpp, English) is linked to this repository and live at https://fincore-cpp.readthedocs.io/en/latest/; the Chinese build is served by GitHub Pages and the language switch maps a reader to the same page on the other host. Platform status and actual URLs are recorded in publication.md and the iteration-10 acceptance record; do not claim an online deployment until the four language/platform combinations have been checked.

Review and exceptions

Doxygen warnings, Sphinx -W -n warnings, broken link checks and translation gaps are separate failure classes. Exact exceptions need a reason, owner and review condition. Do not use global warning suppression or English fallback to obtain a green build.