From 2bf239bbeb4fec595b650a2a87c630596e256b1c Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Wed, 27 Jul 2022 11:24:06 +0200 Subject: [PATCH 1/3] Enable ranges for `Depth` setting in `at-contents` block This patch adds support for passing `UnitRange`s to the `Depth` setting in `at-contents`. This makes it possible to also limit the minimum header level that should be included. `Depth = 2:3` would include only headers with level 2-3, and exclude, in particular, level 1. Fixes #245. --- CHANGELOG.md | 2 ++ docs/src/lib/public.md | 1 + docs/src/man/syntax.md | 5 ++++- src/Documents.jl | 10 ++++++++-- src/Writers/HTMLWriter.jl | 7 +++++-- src/Writers/LaTeXWriter.jl | 3 +++ 6 files changed, 23 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ace091d9e8..2e58de9035 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ **For upgrading:** the easiest way to fix the build is to remove the offending `@ref` links. Alternatively, the `repo` argument to `makedocs` can be set to the appropriate `Remotes.Remote` object that implements the `Remotes.issueurl` function, which would make sure that correct URLs are generated. * ![Enhancement][badge-enhancement] Woodpecker CI is now automatically supported for documentation deployment. ([#1880][github-1880]) +* ![Enhancement][badge-enhancement] The `@contents`-block now support `UnitRange`s for the `Depth` argument. This makes it possible to configure also the *minimal* header depth that should be displayed (`Depth = 2:3`, for example). This is supported by the HTML and the LaTeX/PDF backends. ([#1890][github-1890]) * ![Bugfix][badge-bugfix] Documenter now generates the correct source URLs for docstrings from other packages when the `repo` argument to `makedocs` is set (note: the source links to such docstrings only work if the external package is cloned from GitHub and added as a dev-dependency). However, this change **breaks** the case where the `repo` argument is used to override the main package/repository URL, assuming the repository is cloned from GitHub. ([#1808][github-1808]) * ![Bugfix][badge-bugfix] Documenter no longer uses the `TRAVIS_REPO_SLUG` environment variable to determine the Git remote of non-main repositories (when inferring it from the Git repository configuration has failed), which could previously lead to bad source links. ([#1881][github-1881]) @@ -1114,6 +1115,7 @@ [github-1881]: https://github.com/JuliaDocs/Documenter.jl/pull/1881 [github-1885]: https://github.com/JuliaDocs/Documenter.jl/issues/1885 [github-1886]: https://github.com/JuliaDocs/Documenter.jl/pull/1886 +[github-1890]: https://github.com/JuliaDocs/Documenter.jl/pull/1890 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079 diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index d87981142a..f2c03aaec3 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -8,6 +8,7 @@ See the Internals section of the manual for internal package docs covering all s ```@contents Pages = ["public.md"] +Depth = 2:2 ``` ## Index diff --git a/docs/src/man/syntax.md b/docs/src/man/syntax.md index 77f1b0f2f5..45a19dd6ab 100644 --- a/docs/src/man/syntax.md +++ b/docs/src/man/syntax.md @@ -5,6 +5,7 @@ For supported Markdown syntax, see the [documentation for the Markdown standard ```@contents Pages = ["syntax.md"] +Depth = 2:2 ``` ## `@docs` block @@ -321,7 +322,9 @@ Depth = 5 ```` As with `@index` if `Pages` is not provided then all pages are included. The default -`Depth` value is `2`. +`Depth` value is `2`, i.e. header levels 1 and 2 are included. `Depth` also accept +`UnitRange`s, to make it possible to configure also the minimum header level to be shown. +`Depth = 2:3` can be used to include only headers with levels 2-3, for example. ## `@example` block diff --git a/src/Documents.jl b/src/Documents.jl index bdbaefd4c2..b4cf716b85 100644 --- a/src/Documents.jl +++ b/src/Documents.jl @@ -113,6 +113,7 @@ end struct ContentsNode pages :: Vector{String} # Which pages should be included in contents? Set by user. + mindepth :: Int # Minimum header level that should be displayed. Set by user. depth :: Int # Down to which level should headers be displayed? Set by user. build :: String # Same as for `IndexNode`s. source :: String # Same as for `IndexNode`s. @@ -120,12 +121,15 @@ struct ContentsNode function ContentsNode(; Pages = [], - Depth = 2, + Depth = 1:2, build = error("missing value for `build` in `ContentsNode`."), source = error("missing value for `source` in `ContentsNode`."), others... ) - new(Pages, Depth, build, source, []) + if Depth isa Integer + Depth = 1:Depth + end + new(Pages, Depth.start, Depth.stop, build, source, []) end end @@ -493,6 +497,8 @@ function populate!(contents::ContentsNode, document::Document) for (file, anchors) in filedict for anchor in anchors page = relpath(anchor.file, dirname(contents.build)) + # Note: This only filters based on contents.depth and *not* contents.mindepth. + # Instead the writers who support this adjust this when rendering. if _isvalid(page, contents.pages) && Utilities.header_level(anchor.object) ≤ contents.depth push!(contents.elements, (anchor.order, page, anchor)) end diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 71b62d5104..6c268af176 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -1584,12 +1584,15 @@ function domify(ctx, navnode, contents::Documents.ContentsNode) navnode_url = get_url(ctx, navnode) lb = ListBuilder() for (count, path, anchor) in contents.elements + header = anchor.object + level = Utilities.header_level(header) + # Skip header levels smaller than the requested mindepth + level = level - contents.mindepth + 1 + level < 1 && continue path = joinpath(navnode_dir, path) # links in ContentsNodes are relative to current page path = pretty_url(ctx, relhref(navnode_url, get_url(ctx, path))) - header = anchor.object url = string(path, Anchors.fragment(anchor)) node = a[:href=>url](mdconvert(header.text; droplinks=true)) - level = Utilities.header_level(header) push!(lb, level, node) end domify(lb) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index 9553ce4622..d5363d1795 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -362,6 +362,9 @@ function latex(io::IO, contents::Documents.ContentsNode, page, doc) for (count, path, anchor) in contents.elements header = anchor.object level = Utilities.header_level(header) + # Filter out header levels smaller than the requested mindepth + level = level - contents.mindepth + 1 + level < 1 && continue id = string(hash(string(anchor.id, "-", anchor.nth))) # If we're changing depth, we need to make sure we always print the # correct number of \begin{itemize} and \end{itemize} statements. From 32eebd5ccc3e909353232ff25e7ab484ecb0eafb Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Fri, 29 Jul 2022 16:41:53 +1200 Subject: [PATCH 2/3] Add ref to #245 --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e58de9035..96a7bc1f49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ **For upgrading:** the easiest way to fix the build is to remove the offending `@ref` links. Alternatively, the `repo` argument to `makedocs` can be set to the appropriate `Remotes.Remote` object that implements the `Remotes.issueurl` function, which would make sure that correct URLs are generated. * ![Enhancement][badge-enhancement] Woodpecker CI is now automatically supported for documentation deployment. ([#1880][github-1880]) -* ![Enhancement][badge-enhancement] The `@contents`-block now support `UnitRange`s for the `Depth` argument. This makes it possible to configure also the *minimal* header depth that should be displayed (`Depth = 2:3`, for example). This is supported by the HTML and the LaTeX/PDF backends. ([#1890][github-1890]) +* ![Enhancement][badge-enhancement] The `@contents`-block now support `UnitRange`s for the `Depth` argument. This makes it possible to configure also the *minimal* header depth that should be displayed (`Depth = 2:3`, for example). This is supported by the HTML and the LaTeX/PDF backends. ([#245][github-245], [#1890][github-1890]) * ![Bugfix][badge-bugfix] Documenter now generates the correct source URLs for docstrings from other packages when the `repo` argument to `makedocs` is set (note: the source links to such docstrings only work if the external package is cloned from GitHub and added as a dev-dependency). However, this change **breaks** the case where the `repo` argument is used to override the main package/repository URL, assuming the repository is cloned from GitHub. ([#1808][github-1808]) * ![Bugfix][badge-bugfix] Documenter no longer uses the `TRAVIS_REPO_SLUG` environment variable to determine the Git remote of non-main repositories (when inferring it from the Git repository configuration has failed), which could previously lead to bad source links. ([#1881][github-1881]) @@ -776,6 +776,7 @@ [github-198]: https://github.com/JuliaDocs/Documenter.jl/issues/198 +[github-245]: https://github.com/JuliaDocs/Documenter.jl/issues/245 [github-487]: https://github.com/JuliaDocs/Documenter.jl/issues/487 [github-511]: https://github.com/JuliaDocs/Documenter.jl/issues/511 [github-535]: https://github.com/JuliaDocs/Documenter.jl/issues/535 From b3a53ac491be0f8cf1212d4c328b3e35bc2c1b80 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Sat, 30 Jul 2022 15:02:29 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Morten Piibeleht --- docs/src/man/syntax.md | 2 +- src/Documents.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/man/syntax.md b/docs/src/man/syntax.md index 45a19dd6ab..4da9fb29c7 100644 --- a/docs/src/man/syntax.md +++ b/docs/src/man/syntax.md @@ -322,7 +322,7 @@ Depth = 5 ```` As with `@index` if `Pages` is not provided then all pages are included. The default -`Depth` value is `2`, i.e. header levels 1 and 2 are included. `Depth` also accept +`Depth` value is `2`, i.e. header levels 1 and 2 are included. `Depth` also accepts `UnitRange`s, to make it possible to configure also the minimum header level to be shown. `Depth = 2:3` can be used to include only headers with levels 2-3, for example. diff --git a/src/Documents.jl b/src/Documents.jl index b4cf716b85..a9a9b589f6 100644 --- a/src/Documents.jl +++ b/src/Documents.jl @@ -129,7 +129,7 @@ struct ContentsNode if Depth isa Integer Depth = 1:Depth end - new(Pages, Depth.start, Depth.stop, build, source, []) + new(Pages, first(Depth), last(Depth), build, source, []) end end