Merge branch 'mg/linkcheck-user-agent' of github.com:giordano/Documen…

…ter.jl into mg/linkcheck-user-agent

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * The `User-Agent` header set in the linkcheck HTTP(S) requests can now be customized with the `linkcheck_useragent` option to `makedocs`. ([#2557], [#2562])
 
+### Fixed
+
+* The paths for `size_threshold_ignore` option of `Documenter.HTML` are now correctly normalized and no longer sensitive to platform-dependent differences in path separators. ([#2560], [#2561])
+
 ## Version [v1.6.0] - 2024-08-20
 
 ### Changed
@@ -1881,6 +1885,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2549]: https://github.com/JuliaDocs/Documenter.jl/issues/2549
 [#2551]: https://github.com/JuliaDocs/Documenter.jl/issues/2551
 [#2557]: https://github.com/JuliaDocs/Documenter.jl/issues/2557
+[#2560]: https://github.com/JuliaDocs/Documenter.jl/issues/2560
+[#2561]: https://github.com/JuliaDocs/Documenter.jl/issues/2561
 [#2562]: https://github.com/JuliaDocs/Documenter.jl/issues/2562
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054

assets/html/scss/documenter/_patches.scss

@@ -64,7 +64,7 @@ pre, code {
 // accessibility span. This breaks the dashboard layout of the equation is somewhere far
 // down in the container.
 //
-// Moving all of these accessbility "pixels" to the top-right seems to take care of the
+// Moving all of these accessibility "pixels" to the top-right seems to take care of the
 // issue. An alternative is also to use `position: fixed`, which does not cause the outer
 // container to scroll.
 .katex .katex-mathml {

docs/src/contributing.md

@@ -58,6 +58,12 @@ Follow the style of the surrounding text when making changes. When adding new fe
  * always use fenced code blocks instead of indented blocks;
  * follow the conventions outlined in the Julia documentation page on documentation.
 
+## Changelog
+
+All pull requests that make user visible changes should have a changelog entry
+formatted according to the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+style
+
 ## Tests
 
 ### Unit tests

docs/src/man/hosting.md

@@ -52,7 +52,7 @@ file. Note that the snippet below will not work by itself and must be accompanie
 jobs:
  include:
  - stage: "Documentation"
- julia: 1.6
+ julia: 1
  os: linux
  script:
  - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));
@@ -63,7 +63,7 @@ jobs:
 
 where the `julia:` and `os:` entries decide the worker from which the docs are built and
 deployed. In the example above we will thus build and deploy the documentation from a linux
-worker running Julia 1.6. For more information on how to setup a build stage, see the Travis
+worker running Julia 1 (the latest stable version). For more information on how to setup a build stage, see the Travis
 manual for [Build Stages](https://docs.travis-ci.com/user/build-stages).
 
 The three lines in the `script:` section do the following:
@@ -200,8 +200,8 @@ jobs:
  - uses: actions/checkout@v4
  - uses: julia-actions/setup-julia@v2
  with:
- version: '1.6'
- - uses: julia-actions/cache@v1
+ version: '1'
+ - uses: julia-actions/cache@v2
  - name: Install dependencies
  run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
  - name: Build and deploy
@@ -214,7 +214,7 @@ jobs:
 This will install Julia, checkout the correct commit of your repository, and run the
 build of the documentation. The `julia-version:`, `julia-arch:` and `os:` entries decide
 the environment from which the docs are built and deployed. The example above builds and deploys
-the documentation from an Ubuntu worker running Julia 1.6.
+the documentation from an Ubuntu worker running Julia 1.
 
 !!! tip
  The example above is a basic workflow that should suit most projects. For more information on
@@ -310,7 +310,7 @@ are uploaded to Codecov:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
  - uses: julia-actions/julia-processcoverage@v1
- - uses: codecov/codecov-action@v3
+ - uses: codecov/codecov-action@v4
 ```
 
 ## `docs/Project.toml`

src/html/HTMLWriter.jl

@@ -564,6 +564,9 @@ struct HTML <: Documenter.Writer
  throw(ArgumentError("example_size_threshold must be non-negative, got $(example_size_threshold)"))
  end
  isa(edit_link, Default) && (edit_link = edit_link[])
+ # We use normpath() when we construct the .page value for NavNodes, so we also need to normpath()
+ # these values. This also ensures cross-platform compatibility of the values.
+ size_threshold_ignore = normpath.(size_threshold_ignore)
  new(prettyurls, disable_git, edit_link, repolink, canonical, assets, analytics,
  collapselevel, sidebar_sitename, highlights, mathengine, description, footer,
  ansicolor, lang, warn_outdated, prerender, node, highlightjs,

test/examples/make.jl

@@ -581,7 +581,7 @@ end
  root = examples_root,
  build = "builds/sizethreshold-defaults-fail",
  source = "src.megapage",
- format = Documenter.HTML(size_threshold_ignore = ["index.md"]),
+ format = Documenter.HTML(size_threshold_ignore = ["index.md", "subdir/subpage.md"]),
  debug = true,
  )
  catch e

test/examples/src.megapage/subdir/subpage.md

@@ -0,0 +1,20 @@
+# Megabytepage: subdir
+
+This page in a subdirectory has more than 1MB of HTML too.
+
+```@example
+using Random
+for s in Base.Iterators.partition(randstring(2^20), 80)
+ # Note: the join() is necessary to get strings (as opposed to Vector{Char} objects)
+ # on older Julia versions, since there was a breaking-ish bugfix that changed how
+ # Iterators.partition works with strings. join(::SubString) appears to basically be
+ # a no-op, so it has no real effect on newer Julia versions.
+ #
+ # https://github.com/JuliaLang/julia/issues/45768
+ # https://github.com/JuliaLang/julia/pull/46234
+ #
+ # Note: we _could_ also just print the vectors, but then the HTML files end up being
+ # ~14 MiB.
+ println(join(s))
+end
+```