From 791cd88dfcf1f26a3e506559b065b9dd54e4181b Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 30 Sep 2026 22:15:20 +0200 Subject: [PATCH] Fix raw-TeX formulas and other documentation infrastructure debt (#5736) * Fix math formulas rendering as raw TeX in the published docs The privacy plugin self-hosts MathJax 2.7.0 but drops its ?config=TeX-MML-AM_CHTML query string, so the rehosted script loads no input jax and the 10 formulas across 6 pages render as raw TeX to readers. Remove pymdownx.arithmatex and the MathJax extra_javascript entry, and rewrite the formulas in plain HTML (, ) instead. This also drops a nine-year-old third-party script from every page. Part of #5718 Signed-off-by: Niels Lohmann * Fix publish_documentation triggers and persist unneeded git credentials publish_documentation.yml only triggered on docs/mkdocs/** pushes, but the site also embeds .github/CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, cmake/{clang,gcc}_flags.cmake, .clang-tidy, tools/astyle/.astylerc and tests/fmt_formatter/project/main.cpp via pymdownx.snippets, so changes to those files never republished the site. Extend the path filter to cover them, and switch runs-on from the long-pinned ubuntu-22.04 to ubuntu-latest to match ci_test_documentation. Also add persist-credentials: false to the checkouts in ci_icpx and ci_nvhpc (ubuntu.yml) and msvc-vs2026/msvc-arm64 (windows.yml), none of which pushes with git, matching every other checkout in these workflows. Part of #5718 Signed-off-by: Niels Lohmann * Fix example build: broken debug echo, deprecations hidden for everything docs/Makefile's debug echo used a space instead of a comma in $(call cxx_standard ...), so it always printed an empty standard. Every example was also compiled with -Wno-deprecated-declarations, which would silently hide an accidental deprecated-API call in any of them. Factor the duplicated compile flags into EXAMPLE_CPPFLAGS/ EXAMPLE_WARNFLAGS, build with -Werror=deprecated-declarations by default, and only allow the three examples that intentionally document deprecated API (the DEPRECATED_EXAMPLES list) to suppress it. Part of #5718 Signed-off-by: Niels Lohmann * Fix check_structure.py NOLINT parsing and an off-by-one report line `line.strip("")` strips any of the characters in those sets from both ends, not a literal prefix; it only happened to work for "Examples". A NOLINT'd section name starting with N, O, L, I or T (e.g. "Notes", "Template parameters", "Iterator invalidation", "Literals") was silently mangled, so the suppression did not apply and the checker could report a spurious missing/misordered section. Parse the comment with a regex instead. The same fragile strip() pattern was used for heading text; replace it with a plain prefix slice. Also fix the admonition_title report, which used the 0-based line index while every other report in the file uses lineno+1. Part of #5718 Signed-off-by: Niels Lohmann * Fix docset README's non-existent make target and stale fallback URL The README told readers to run `make nlohmann_json.docset`, but the Makefile's targets are `all`, `JSON_for_Modern_C++.docset` and `install_docset_zeal`; the documented command has failed with "No rule to make target" since #2967 (2021). Point the README at the real target and folder name. Info.plist's DashDocSetFallbackURL also still pointed at the old nlohmann.github.io/json/ URL instead of the canonical https://json.nlohmann.me/ from mkdocs.yml's site_url. Leave list_missing_pages/list_removed_paths alone: they may become redundant once #5638's check_docset() lands, which is a follow-up. Part of #5718 Signed-off-by: Niels Lohmann * Remove two leftover Doxygen-era .link files from the examples directory parse__iterator_pair.link and parse__pointers.link each held only a Wandbox "online" permalink from the old Doxygen docs. #3071 deleted every other .link file in 2021; these two came in through a parallel PR (#3100) and were never referenced by any page, script or config. Part of #5718 Signed-off-by: Niels Lohmann * Fix MacPorts CMake example to include its own snippet files The MacPorts "Example: CMake" block included integration/homebrew/example.cpp and integration/homebrew/CMakeLists.txt instead of the MacPorts files right next to it, a copy-paste slip from the Homebrew section. Nothing referenced integration/macports/CMakeLists.txt as a result. The page rendered correctly only because the homebrew, macports and vcpkg/CMakeLists.txt snippets are byte-identical, so a future edit to the MacPorts files would not have shown up on the page. Part of #5718 item 6 Signed-off-by: Niels Lohmann * Do not persist git credentials in publish_documentation's checkout The checkout step in publish_documentation.yml left the default persist-credentials: true, so GITHUB_TOKEN stayed writable in .git/config for the rest of the job (zizmor's artipacked finding). The Deploy documentation step authenticates through its own github_token input to peaceiris/actions-gh-pages and does not push with the checked-out credentials, so persist-credentials: false is safe here, matching every other checkout in the workflow set. Overlaps #5638, which edits this same checkout step (adds fetch-depth: 0); expect a rebase conflict there. Part of #5718 item 2 Signed-off-by: Niels Lohmann * Replace list_missing_pages/list_removed_paths with a comm(1)-based diff The docset Makefile's list_missing_pages ran one sqlite3 query per mkdocs page, and list_removed_paths nested a loop over all mkdocs pages inside a loop over all docset index paths (O(n*m) shell iteration). Issue #5718 item 5 suggested removing or reducing these targets once #5638's check_docset() lands, but that PR is still open and covers only API pages and macros, not the full page set these targets check. Replace the loops with two sorted path lists (DOCSET_PAGE_PATHS from mkdocs' markdown sources, DOCSET_INDEX_PATHS from the built docset index) compared with a single comm(1) call each, verified to produce output identical to the old loops against the current docSet.dsidx. The sed expression used '#' as its delimiter, which GNU Make reads as a comment character even inside a variable assignment, truncating the line and orphaning the closing paren of $(shell ...) ("unterminated call to function 'shell': missing ')'"). Use '@' as the delimiter instead. Part of #5718 item 5 Signed-off-by: Niels Lohmann --------- Signed-off-by: Niels Lohmann --- .github/workflows/publish_documentation.yml | 14 +++++++- .github/workflows/ubuntu.yml | 4 +++ .github/workflows/windows.yml | 4 +++ docs/Makefile | 21 +++++++++--- docs/docset/Info.plist | 2 +- docs/docset/Makefile | 34 +++++++------------ docs/docset/README.md | 5 +-- .../docs/api/basic_json/number_integer_t.md | 2 +- .../docs/api/basic_json/number_unsigned_t.md | 2 +- .../mkdocs/docs/api/basic_json/parse_error.md | 2 +- .../docs/examples/parse__iterator_pair.link | 1 - .../mkdocs/docs/examples/parse__pointers.link | 1 - .../docs/features/binary_formats/bjdata.md | 2 +- docs/mkdocs/docs/features/types/index.md | 2 +- .../docs/features/types/number_handling.md | 8 ++--- .../docs/integration/package_managers.md | 4 +-- docs/mkdocs/mkdocs.yml | 4 --- docs/mkdocs/scripts/check_structure.py | 10 +++--- 18 files changed, 69 insertions(+), 53 deletions(-) delete mode 100644 docs/mkdocs/docs/examples/parse__iterator_pair.link delete mode 100644 docs/mkdocs/docs/examples/parse__pointers.link diff --git a/.github/workflows/publish_documentation.yml b/.github/workflows/publish_documentation.yml index 189d95419..f65d63a92 100644 --- a/.github/workflows/publish_documentation.yml +++ b/.github/workflows/publish_documentation.yml @@ -7,6 +7,16 @@ on: - develop paths: - docs/mkdocs/** + # the site also embeds these files via pymdownx.snippets + # (mkdocs.yml sets restrict_base_path: false for this) + - .clang-tidy + - .github/CODE_OF_CONDUCT.md + - .github/CONTRIBUTING.md + - .github/SECURITY.md + - cmake/clang_flags.cmake + - cmake/gcc_flags.cmake + - tests/fmt_formatter/project/main.cpp + - tools/astyle/.astylerc workflow_dispatch: # we don't want to have concurrent jobs, and we don't want to cancel running jobs to avoid broken publications @@ -23,7 +33,7 @@ jobs: contents: write if: github.repository == 'nlohmann/json' - runs-on: ubuntu-22.04 + runs-on: ubuntu-latest steps: - name: Harden Runner uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1 @@ -31,6 +41,8 @@ jobs: egress-policy: audit - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Install virtual environment run: make install_venv -C docs/mkdocs diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index d8f15e3dd..fb3cd4148 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -346,6 +346,8 @@ jobs: container: intel/oneapi-hpckit:latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Get latest CMake and ninja uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2 - name: Run CMake @@ -358,6 +360,8 @@ jobs: container: nvcr.io/nvidia/nvhpc:25.5-devel-cuda12.9-ubuntu22.04 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Get latest CMake and ninja uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2 - name: Run CMake diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index ea742773f..65169eac4 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -87,6 +87,8 @@ jobs: steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Get latest CMake and ninja uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2 - name: Set extra CXX_FLAGS for latest std_version @@ -123,6 +125,8 @@ jobs: steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Run CMake (Release) run: cmake -S . -B build -G "Visual Studio 18 2026" -A ARM64 -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="/W4 /WX" if: matrix.build_type == 'Release' diff --git a/docs/Makefile b/docs/Makefile index 0412fb90a..a61c30182 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -11,20 +11,31 @@ EXAMPLES = $(wildcard mkdocs/docs/examples/*.cpp) cxx_standard = $(lastword c++11 $(filter c++%, $(subst ., ,$1))) +# common compile flags for the stand-alone example files +EXAMPLE_CPPFLAGS = -I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0 +EXAMPLE_WARNFLAGS = -Werror=deprecated-declarations + +# examples that document deprecated API and are allowed to use it +DEPRECATED_EXAMPLES = $(addprefix mkdocs/docs/examples/, \ + json_pointer__operator__equal_stringtype \ + json_pointer__operator__notequal_stringtype \ + json_pointer__operator_string_t) +$(DEPRECATED_EXAMPLES:=.output) $(DEPRECATED_EXAMPLES:=.test): EXAMPLE_WARNFLAGS = -Wno-deprecated-declarations + # create output from a stand-alone example file %.output: %.cpp - @echo "standard $(call cxx_standard $(<:.cpp=))" + @echo "standard $(call cxx_standard,$(<:.cpp=))" $(MAKE) $(<:.cpp=) \ - CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \ - CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations" + CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \ + CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)" ./$(<:.cpp=) > $@ rm $(<:.cpp=) # compare created output with current output of the example files %.test: %.cpp $(MAKE) $(<:.cpp=) \ - CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \ - CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations" + CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \ + CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)" ./$(<:.cpp=) > $@ diff $@ $(<:.cpp=.output) rm $(<:.cpp=) $@ diff --git a/docs/docset/Info.plist b/docs/docset/Info.plist index 772ec08af..8f63bc5dd 100644 --- a/docs/docset/Info.plist +++ b/docs/docset/Info.plist @@ -13,7 +13,7 @@ dashIndexFilePath index.html DashDocSetFallbackURL - https://nlohmann.github.io/json/ + https://json.nlohmann.me/ isJavaScriptEnabled diff --git a/docs/docset/Makefile b/docs/docset/Makefile index 9f4363462..b638390db 100644 --- a/docs/docset/Makefile +++ b/docs/docset/Makefile @@ -52,35 +52,25 @@ install_docset_zeal: JSON_for_Modern_C++.docset mkdir -p $$docset_root; \ cp -r JSON_for_Modern_C++.docset $$docset_root/ +# both targets below compare the docset search index with the mkdocs page +# set. They share the same normalization (docs/foo/index.md and +# docs/foo.md both become foo/index.html, the URL mkdocs itself would +# give the page; the top-level index.md is excluded, as it is not part +# of the hand-curated docSet.sql) and use comm(1) on two sorted lists +# instead of running a sqlite3 query, or an O(n*m) nested shell loop, +# once per page. +DOCSET_INDEX_PATHS=$(shell sqlite3 docSet.dsidx "SELECT DISTINCT path FROM searchIndex" | sort) +DOCSET_PAGE_PATHS=$(shell echo '$(MKDOCS_PAGES)' | tr ' ' '\n' | grep -v '^index\.md$$' | $(SED) -E 's@/index\.md$$@/index.html@; s@\.md$$@/index.html@' | sort) + # list mkdocs pages missing from the docset index .PHONY: list_missing_pages list_missing_pages: docSet.dsidx - @for page in $(MKDOCS_PAGES); do \ - case "$$page" in \ - */index.md) path=$${page/\/index.md/} ;; \ - *) path=$${page/.md/} ;; \ - esac; \ - if [ "x$$page" != "xindex.md" -a "x$$(sqlite3 docSet.dsidx "SELECT COUNT(*) FROM searchIndex WHERE path='$$path/index.html'")" = "x0" ]; then \ - echo $$page; \ - fi \ - done + @comm -23 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n') # list paths in the docset index without a corresponding mkdocs page .PHONY: list_removed_paths list_removed_paths: docSet.dsidx - @for path in $$(sqlite3 docSet.dsidx "SELECT path FROM searchIndex"); do \ - page=$${path/\/index.html/.md}; \ - page_index=$${path/index.html/index.md}; \ - page_found=0; \ - for p in $(MKDOCS_PAGES); do \ - if [ "x$$p" = "x$$page" -o "x$$p" = "x$$page_index" ]; then \ - page_found=1; \ - fi \ - done; \ - if [ "x$$page_found" = "x0" ]; then \ - echo $$path; \ - fi \ - done + @comm -13 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n') .PHONY: clean clean: diff --git a/docs/docset/README.md b/docs/docset/README.md index 79a778eb8..9d962a91c 100644 --- a/docs/docset/README.md +++ b/docs/docset/README.md @@ -7,10 +7,11 @@ documentation browsers like [Dash](https://kapeli.com/dash), [Velocity](https:// The docset can be created with ```sh -make nlohmann_json.docset +make JSON_for_Modern_C++.docset ``` -The generated folder `nlohmann_json.docset` can then be opened in the documentation browser. +The generated folder `JSON_for_Modern_C++.docset` can then be opened in the documentation browser. `make all` builds a +`JSON_for_Modern_C++.tgz` archive instead, and `make install_docset_zeal` installs the docset for Zeal directly. A recent version is also part of the [Dash user contributions](https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/JSON_for_Modern_C%2B%2B). diff --git a/docs/mkdocs/docs/api/basic_json/number_integer_t.md b/docs/mkdocs/docs/api/basic_json/number_integer_t.md index 9a2ffab7f..9b1d7ae74 100644 --- a/docs/mkdocs/docs/api/basic_json/number_integer_t.md +++ b/docs/mkdocs/docs/api/basic_json/number_integer_t.md @@ -51,7 +51,7 @@ range will yield over/underflow when used in a constructor. During deserializati will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md). [RFC 8259](https://tools.ietf.org/html/rfc8259) further states: -> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are +> Note that when such software is used, numbers that are integers and are in the range [-253+1, 253-1] are > interoperable in the sense that implementations will agree exactly on their numeric values. As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is diff --git a/docs/mkdocs/docs/api/basic_json/number_unsigned_t.md b/docs/mkdocs/docs/api/basic_json/number_unsigned_t.md index 674f7711d..f4799b2e9 100644 --- a/docs/mkdocs/docs/api/basic_json/number_unsigned_t.md +++ b/docs/mkdocs/docs/api/basic_json/number_unsigned_t.md @@ -52,7 +52,7 @@ when used in a constructor. During deserialization, too large or small integer n as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md). [RFC 8259](https://tools.ietf.org/html/rfc8259) further states: -> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are +> Note that when such software is used, numbers that are integers and are in the range [-253+1, 253-1] are > interoperable in the sense that implementations will agree exactly on their numeric values. As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported diff --git a/docs/mkdocs/docs/api/basic_json/parse_error.md b/docs/mkdocs/docs/api/basic_json/parse_error.md index 74e16f41a..c3f49ef13 100644 --- a/docs/mkdocs/docs/api/basic_json/parse_error.md +++ b/docs/mkdocs/docs/api/basic_json/parse_error.md @@ -54,7 +54,7 @@ classDiagram ## Notes -For an input with $n$ bytes, 1 is the index of the first character and $n+1$ is the index of the terminating null byte +For an input with n bytes, 1 is the index of the first character and n+1 is the index of the terminating null byte or the end of file. This also holds true when reading a byte vector for binary formats. ## Examples diff --git a/docs/mkdocs/docs/examples/parse__iterator_pair.link b/docs/mkdocs/docs/examples/parse__iterator_pair.link deleted file mode 100644 index f464e54c8..000000000 --- a/docs/mkdocs/docs/examples/parse__iterator_pair.link +++ /dev/null @@ -1 +0,0 @@ -online \ No newline at end of file diff --git a/docs/mkdocs/docs/examples/parse__pointers.link b/docs/mkdocs/docs/examples/parse__pointers.link deleted file mode 100644 index 9a93ef1c5..000000000 --- a/docs/mkdocs/docs/examples/parse__pointers.link +++ /dev/null @@ -1 +0,0 @@ -online \ No newline at end of file diff --git a/docs/mkdocs/docs/features/binary_formats/bjdata.md b/docs/mkdocs/docs/features/binary_formats/bjdata.md index a0c84edaf..cd73b07e2 100644 --- a/docs/mkdocs/docs/features/binary_formats/bjdata.md +++ b/docs/mkdocs/docs/features/binary_formats/bjdata.md @@ -61,7 +61,7 @@ The library uses the following mapping from JSON values types to BJData types ac The following values can **not** be converted to a BJData value: - - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical) + - strings with more than 18446744073709551615 bytes, i.e., 264-1 bytes (theoretical) !!! info "Unused BJData markers" diff --git a/docs/mkdocs/docs/features/types/index.md b/docs/mkdocs/docs/features/types/index.md index e6078b825..354acd5ac 100644 --- a/docs/mkdocs/docs/features/types/index.md +++ b/docs/mkdocs/docs/features/types/index.md @@ -273,7 +273,7 @@ When the default type is used, the maximal unsigned integer number that can be s [RFC 8259](https://tools.ietf.org/html/rfc8259) further states: -> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are interoperable in the sense that implementations will agree exactly on their numeric values. +> Note that when such software is used, numbers that are integers and are in the range [-253+1, 253-1] are interoperable in the sense that implementations will agree exactly on their numeric values. As this range is a subrange of the exactly supported range [`INT64_MIN`, `INT64_MAX`], this class's integer type is interoperable. diff --git a/docs/mkdocs/docs/features/types/number_handling.md b/docs/mkdocs/docs/features/types/number_handling.md index cf37b044a..ef43054e5 100644 --- a/docs/mkdocs/docs/features/types/number_handling.md +++ b/docs/mkdocs/docs/features/types/number_handling.md @@ -48,7 +48,7 @@ On number interoperability, the following remarks are made: for numeric magnitude and precision than is widely available. Note that when such software is used, numbers that are integers and - are in the range $[-2^{53}+1, 2^{53}-1]$ are interoperable in the + are in the range [-253+1, 253-1] are interoperable in the sense that implementations will agree exactly on their numeric values. @@ -95,9 +95,9 @@ This is the same behavior as the code `#!c double x = 3.141592653589793238462643 !!! success "Interoperability" - - The library is interoperable with respect to the specification, because its supported range $[-2^{63}, 2^{64}-1]$ is - larger than the described range $[-2^{53}+1, 2^{53}-1]$. - - All integers outside the range $[-2^{63}, 2^{64}-1]$, as well as floating-point numbers are stored as `double`. + - The library is interoperable with respect to the specification, because its supported range [-263, 264-1] is + larger than the described range [-253+1, 253-1]. + - All integers outside the range [-263, 264-1], as well as floating-point numbers are stored as `double`. This also concurs with the specification above. ### Zeros diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md index 792a0fa5a..28f95e584 100644 --- a/docs/mkdocs/docs/integration/package_managers.md +++ b/docs/mkdocs/docs/integration/package_managers.md @@ -678,11 +678,11 @@ to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) p 1. Create the following files: ```cpp title="example.cpp" - --8<-- "integration/homebrew/example.cpp" + --8<-- "integration/macports/example.cpp" ``` ```cmake title="CMakeLists.txt" - --8<-- "integration/homebrew/CMakeLists.txt" + --8<-- "integration/macports/CMakeLists.txt" ``` 2. Install the package: diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index b31fb1734..4bd207e60 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -351,7 +351,6 @@ markdown_extensions: - toc: permalink: true - md_in_html - - pymdownx.arithmatex - pymdownx.betterem: smart_enable: all - pymdownx.caret @@ -443,6 +442,3 @@ plugins: extra_css: - css/custom.css - -extra_javascript: - - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML diff --git a/docs/mkdocs/scripts/check_structure.py b/docs/mkdocs/scripts/check_structure.py index c8d637d06..78ad0d9fa 100755 --- a/docs/mkdocs/scripts/check_structure.py +++ b/docs/mkdocs/scripts/check_structure.py @@ -79,9 +79,9 @@ def check_structure() -> None: report("whitespace/line_length", f"{file}:{lineno+1} ({current_section})", f"line is too long ({len(line)} vs. 160 chars)") # sections in `` comments are treated as present - if line.startswith("") + nolint_match = re.match(r"", line) + if nolint_match: + current_section = nolint_match.group(1) existing_sections.append(current_section) # check if sections are correct @@ -97,7 +97,7 @@ def check_structure() -> None: if len(unexpected): report("style/numbering", f"{file}:{lineno} ({current_section})", f'unexpected overloads: {", ".join([f"({x})" for x in unexpected])}') - current_section = line.strip("## ") + current_section = line[3:] existing_sections.append(current_section) if current_section in expected_sections: @@ -141,7 +141,7 @@ def check_structure() -> None: # check that non-example admonitions have titles untitled_admonition = re.match(r"^(\?\?\?|!!!) ([^ ]+)$", line) if untitled_admonition and untitled_admonition.group(2) != "example": - report("style/admonition_title", f"{file}:{lineno} ({current_section})", f'"{untitled_admonition.group(2)}" admonitions should have a title') + report("style/admonition_title", f"{file}:{lineno+1} ({current_section})", f'"{untitled_admonition.group(2)}" admonitions should have a title') previous_line = line