diff --git a/.github/workflows/cli-drift.yml b/.github/workflows/cli-drift.yml index e535673..235c7bd 100644 --- a/.github/workflows/cli-drift.yml +++ b/.github/workflows/cli-drift.yml @@ -17,7 +17,6 @@ on: pull_request: paths: - 'docs/docs/reference/cli.md' - - 'docs/_data/cli-global-flags.yaml' - 'scripts/check-cli-drift.py' - '.github/workflows/cli-drift.yml' workflow_dispatch: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 28fcbb5..e6bbdc8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -58,6 +58,17 @@ jobs: working-directory: docs run: poetry run zensical build --strict + # zensical doesn't run Jinja (the macros plugin was silently ignored and + # the CLI page shipped a raw `{% for %}` loop), and --strict doesn't + # notice. Any template syntax left in a built page fails the build. + - name: No unrendered template syntax + working-directory: docs + run: | + if grep -rl --include='*.html' -e '{{ ' -e '{% ' site; then + echo "::error::the pages above contain unrendered {{ }} or {% %}" + exit 1 + fi + - name: Upload Pages artifact if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' uses: actions/upload-pages-artifact@v5 diff --git a/docs/_data/cli-global-flags.yaml b/docs/_data/cli-global-flags.yaml deleted file mode 100644 index d0b20d0..0000000 --- a/docs/_data/cli-global-flags.yaml +++ /dev/null @@ -1,9 +0,0 @@ -global_flags: - - flag: "`-p`, `--path `" - effect: "Run against `` instead of the current directory." - - flag: "`-v`, `--verbose` (repeatable: `-vv`, `-vvv`)" - effect: "Raise log verbosity (info / debug / trace) for `comline-core` diagnostics." - - flag: "`-q`, `--quiet`" - effect: "Only errors. Conflicts with `-v`." - - flag: "`--plain`" - effect: "No color, symbols, emoji or spinner — for logs and CI." diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index e8e6c24..de80806 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -65,8 +65,10 @@ and `lib` mode. | Flag | Effect | |---|---| -{% for row in global_flags %}| {{ row.flag }} | {{ row.effect }} | -{% endfor %} +| `-p`, `--path ` | Run against `` instead of the current directory. | +| `-v`, `--verbose` (repeatable: `-vv`, `-vvv`) | Raise log verbosity (info / debug / trace) for `comline-core` diagnostics. | +| `-q`, `--quiet` | Only errors. Conflicts with `-v`. | +| `--plain` | No color, symbols, emoji or spinner — for logs and CI. | `RUST_LOG` overrides the verbosity flags. `NO_COLOR` strips color. stdout is reserved for machine output (`completions` and `targets` write there); diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 8ea4d1b..3302169 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -180,12 +180,8 @@ theme: # TODO: The social plugin is disabled due to not Cairo lib not being available on Nix -plugins: +# plugins: # - social - - macros: - include_yaml: - - _data/cli-global-flags.yaml - render_by_default: false extra: # social: diff --git a/docs/poetry.lock b/docs/poetry.lock index 2a3e7f1..8c58126 100755 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -302,18 +302,6 @@ python-dateutil = ">=2.8.1" [package.extras] dev = ["flake8", "markdown", "twine", "wheel"] -[[package]] -name = "hjson" -version = "3.1.0" -description = "Hjson, a user interface for JSON." -optional = false -python-versions = "*" -groups = ["main"] -files = [ - {file = "hjson-3.1.0-py3-none-any.whl", hash = "sha256:65713cdcf13214fb554eb8b4ef803419733f4f5e551047c9b711098ab7186b89"}, - {file = "hjson-3.1.0.tar.gz", hash = "sha256:55af475a27cf83a7969c808399d7bccdec8fb836a07ddbd574587593b9cdcf75"}, -] - [[package]] name = "idna" version = "3.19" @@ -546,34 +534,6 @@ mergedeep = ">=1.3.4" platformdirs = ">=2.2.0" pyyaml = ">=5.1" -[[package]] -name = "mkdocs-macros-plugin" -version = "1.5.0" -description = "Unleash the power of MkDocs with macros and variables" -optional = false -python-versions = ">=3.8" -groups = ["main"] -files = [ - {file = "mkdocs_macros_plugin-1.5.0-py3-none-any.whl", hash = "sha256:c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f"}, - {file = "mkdocs_macros_plugin-1.5.0.tar.gz", hash = "sha256:12aa45ce7ecb7a445c66b9f649f3dd05e9b92e8af6bc65e4acd91d26f878c01f"}, -] - -[package.dependencies] -hjson = "*" -jinja2 = "*" -mkdocs = ">=0.17" -packaging = "*" -pathspec = "*" -python-dateutil = "*" -pyyaml = "*" -requests = "*" -super-collections = ">=0.6.2" -termcolor = "*" - -[package.extras] -doc = ["mkdocs-mermaid2-plugin"] -test = ["mkdocs-d2-plugin", "mkdocs-include-markdown-plugin", "mkdocs-macros-test", "mkdocs-material (>=6.2)", "mkdocs-test (>=0.6.0)", "pytest"] - [[package]] name = "mkdocs-material" version = "9.7.7" @@ -974,39 +934,6 @@ files = [ {file = "six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81"}, ] -[[package]] -name = "super-collections" -version = "0.6.2" -description = "file: README.md" -optional = false -python-versions = ">=3.8" -groups = ["main"] -files = [ - {file = "super_collections-0.6.2-py3-none-any.whl", hash = "sha256:291b74d26299e9051d69ad9d89e61b07b6646f86a57a2f5ab3063d206eee9c56"}, - {file = "super_collections-0.6.2.tar.gz", hash = "sha256:0c8d8abacd9fad2c7c1c715f036c29f5db213f8cac65f24d45ecba12b4da187a"}, -] - -[package.dependencies] -hjson = "*" - -[package.extras] -test = ["pytest (>=7.0)", "pyyaml", "rich"] - -[[package]] -name = "termcolor" -version = "3.3.0" -description = "ANSI color formatting for output in terminal" -optional = false -python-versions = ">=3.10" -groups = ["main"] -files = [ - {file = "termcolor-3.3.0-py3-none-any.whl", hash = "sha256:cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5"}, - {file = "termcolor-3.3.0.tar.gz", hash = "sha256:348871ca648ec6a9a983a13ab626c0acce02f515b9e1983332b17af7979521c5"}, -] - -[package.extras] -tests = ["pytest", "pytest-cov"] - [[package]] name = "tomli" version = "2.4.1" @@ -1176,4 +1103,4 @@ tomli = ">=2.4.0" [metadata] lock-version = "2.1" python-versions = "^3.14" -content-hash = "5f9dcdc674ff05c34a6e2ec8207c38590b83940e8931e4cfad45ca4b756f51d6" +content-hash = "c044feecea816c4ccfe369c5975a1fb097f901b65a335764c8c5d56eb66224d5" diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 421aff0..31bfb1a 100755 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -16,7 +16,6 @@ pillow = "^12.3.0" mike = "^2.2.0" zensical = ">=0.0.57,<0.1.0" comline-pygments = { path = "pygments-comline", develop = true } -mkdocs-macros-plugin = "^1.5.0" diff --git a/scripts/check-cli-drift.py b/scripts/check-cli-drift.py index d985c0b..eb03476 100755 --- a/scripts/check-cli-drift.py +++ b/scripts/check-cli-drift.py @@ -30,9 +30,6 @@ ROOT = Path(__file__).resolve().parent.parent DOCS_PAGE = ROOT / "docs/docs/reference/cli.md" -# The page's tables may be assembled at build time from `_data/*.yaml` by the -# macros extension, so the documented surface is the page *plus* that data. -DATA_DIR = ROOT / "docs/_data" # Inherited by every subcommand; documented once under "Global flags". GLOBAL_FLAGS = {"--path", "--verbose", "--quiet", "--plain"} @@ -130,12 +127,7 @@ def main() -> int: if not DOCS_PAGE.exists(): sys.exit(f"error: {DOCS_PAGE} not found") - sources = [DOCS_PAGE.read_text(encoding="utf-8")] - if DATA_DIR.is_dir(): - sources += [ - f.read_text(encoding="utf-8") for f in sorted(DATA_DIR.glob("*.yaml")) - ] - doc_commands, doc_flags = documented("\n".join(sources)) + doc_commands, doc_flags = documented(DOCS_PAGE.read_text(encoding="utf-8")) root_help = run_help([]) real_commands = parse_commands(root_help)