Support UnitRange for Depth configuration in at-contents block

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. ([#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])
 
@@ -775,6 +776,7 @@
 
 <!-- issue link definitions -->
 [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
@@ -1114,6 +1116,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
 <!-- end of issue link definitions -->
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079

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

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
 

src/Documents.jl

@@ -113,19 +113,23 @@ 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.
     elements    :: Vector         # (order, page, anchor)-tuple for constructing links.
 
     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

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)

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.