Merge branch 'JuliaDocs:master' into master

.github/workflows/regression-tests.yml

@@ -0,0 +1,79 @@
+name: regression-tests
+on:
+  workflow_dispatch:
+jobs:
+  test-dependent-packages:
+    name: run-tests-${{ matrix.package }}
+    runs-on: ubuntu-latest
+    env:
+      PACKAGE: ${{ matrix.package }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: 'DocumenterCitations'
+          - package: 'DocumenterMermaid'
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - name: Test
+        shell: julia --color=yes {0}
+        run: |
+          import Pkg
+          Pkg.develop(Pkg.PackageSpec(; path = pwd()))
+          Pkg.develop(ENV["PACKAGE"])
+          Pkg.test(ENV["PACKAGE"])
+  test-documentation-build:
+    name: doc-build-${{ matrix.package }}
+    runs-on: ubuntu-latest
+    env:
+      PACKAGE: ${{ matrix.package }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: 'MathOptInterface'
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}- 
+      - name: install-and-build-documentation
+        shell: julia --color=yes {0}
+        run: |
+          import Pkg
+          # Install the PACKAGE into `Pkg.devdir()`
+          Pkg.develop(ENV["PACKAGE"])
+          # Assume that there is an docs/Project.toml
+          doc_path = joinpath(Pkg.devdir(), ENV["PACKAGE"], "docs")
+          Pkg.activate(doc_path)
+          # Change the TOML to include the package and this version of Documenter
+          Pkg.develop(ENV["PACKAGE"])
+          Pkg.develop(Pkg.PackageSpec(path=pwd()))
+          # Install
+          Pkg.instantiate()
+          # Build the docs
+          include(joinpath(doc_path, "make.jl"))

CHANGELOG.md

@@ -3,6 +3,23 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## UNRELEASED
+
+### Changed
+
+* `id` anchors may now start with a numeric digit. ([#744]), ([#2325])
+
+### Fixed
+
+* Enabled text wrapping in docstring header on smaller screens. ([#2293], [#2307])
+* Fixed breadcrumb overflow with long page title on narrow screens (mobile). ([#2317])
+
+## Version [v1.1.2] - 2023-10-23
+
+### Fixed
+
+* Non-breaking spaces are now properly converted as "~" in the `LaTeXWriter`. ([#2300])
+
 ## Version [v1.1.1] - 2023-10-12
 
 ### Fixed
@@ -1264,6 +1281,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [v1.0.1]: https://github.com/JuliaDocs/Documenter.jl/releases/tag/v1.0.1
 [v1.1.0]: https://github.com/JuliaDocs/Documenter.jl/releases/tag/v1.1.0
 [v1.1.1]: https://github.com/JuliaDocs/Documenter.jl/releases/tag/v1.1.1
+[v1.1.2]: https://github.com/JuliaDocs/Documenter.jl/releases/tag/v1.1.2
 [#198]: https://github.com/JuliaDocs/Documenter.jl/issues/198
 [#245]: https://github.com/JuliaDocs/Documenter.jl/issues/245
 [#487]: https://github.com/JuliaDocs/Documenter.jl/issues/487
@@ -1275,6 +1293,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#631]: https://github.com/JuliaDocs/Documenter.jl/issues/631
 [#697]: https://github.com/JuliaDocs/Documenter.jl/issues/697
 [#706]: https://github.com/JuliaDocs/Documenter.jl/issues/706
+[#744]: https://github.com/JuliaDocs/Documenter.jl/issues/744
 [#756]: https://github.com/JuliaDocs/Documenter.jl/issues/756
 [#764]: https://github.com/JuliaDocs/Documenter.jl/issues/764
 [#774]: https://github.com/JuliaDocs/Documenter.jl/issues/774
@@ -1711,6 +1730,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2280]: https://github.com/JuliaDocs/Documenter.jl/issues/2280
 [#2281]: https://github.com/JuliaDocs/Documenter.jl/issues/2281
 [#2285]: https://github.com/JuliaDocs/Documenter.jl/issues/2285
+[#2293]: https://github.com/JuliaDocs/Documenter.jl/issues/2293
+[#2300]: https://github.com/JuliaDocs/Documenter.jl/issues/2300
+[#2307]: https://github.com/JuliaDocs/Documenter.jl/issues/2307
+[#2317]: https://github.com/JuliaDocs/Documenter.jl/issues/2317
+[#2323]: https://github.com/JuliaDocs/Documenter.jl/issues/2325
 [JuliaLang/julia#29344]: https://github.com/JuliaLang/julia/issues/29344
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054

Project.toml

@@ -1,6 +1,6 @@
 name = "Documenter"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "1.1.1"
+version = "1.1.2"
 
 [deps]
 ANSIColoredPrinters = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
@@ -27,12 +27,26 @@ Unicode = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 [compat]
 ANSIColoredPrinters = "0.0.1"
 AbstractTrees = "0.4"
+Base64 = "1.6"
+Dates = "1.6"
 DocStringExtensions = "0.4, 0.5, 0.6, 0.7, 0.8, 0.9"
+Downloads = "1.4"
 IOCapture = "0.2"
+InteractiveUtils = "1.6"
 JSON = "0.19, 0.20, 0.21"
+LibGit2 = "1.6"
+Logging = "1.6"
+Markdown = "1.6"
 MarkdownAST = "0.1.1"
+Pkg = "1.6"
 PrecompileTools = "1"
 RegistryInstances = "0.1"
+Random = "1.6"
+REPL = "1.6"
+SHA = "0.7, 1.6"
+Test = "1.6"
+Unicode = "1.6"
+UUIDs = "1.6"
 julia = "1.6"
 
 [extras]

assets/html/scss/documenter/components/_docstring.scss

@@ -17,6 +17,7 @@
     box-shadow: $card-header-shadow;
     box-shadow: none;
     border-bottom: 1px solid $border;
+    overflow: auto;
 
     code {
       background-color: transparent;

assets/html/scss/documenter/layout/_main.scss

@@ -51,6 +51,7 @@
       display: flex;
       .breadcrumb {
         flex-grow: 1;
+        overflow-x: hidden;
       }
 
       .docs-sidebar-button {

docs/src/man/latex.md

@@ -170,4 +170,27 @@ mathengine = MathJax3(Dict(
 ))
 ```
 
+The syntax is slightly different if using KaTeX, the following example is what you might include in your `makedocs` function:
+
+```julia
+makedocs(
+    format = Documenter.HTML(; mathengine=
+        Documenter.KaTeX(
+            Dict(:delimiters => [
+                Dict(:left => raw"$",   :right => raw"$",   display => false),
+                Dict(:left => raw"$$",  :right => raw"$$",  display => true),
+                Dict(:left => raw"\[",  :right => raw"\]",  display => true),
+                ],
+                :macros => Dict("\\RR" => "\\mathbb{R}",
+                    raw"\Xi" => raw"X_{i}",
+                    raw"\Ru" => raw"R_{\mathrm{univ.}}",
+                    raw"\Pstd" => raw"P_{\mathrm{std}}",
+                    raw"\Tstd" => raw"T_{\mathrm{std}}",
+                ),
+            )
+        )
+    )
+)
+```
+
 [`MathJax2`](@ref), [`MathJax3`](@ref) and [`KaTeX`](@ref) are available types for `mathengine`.

src/latex/LaTeXWriter.jl

@@ -804,6 +804,7 @@ latex(io::Context, node::Node, ::MarkdownAST.LineBreak) = _println(io, "\\\\")
 
 const _latexescape_chars = Dict{Char, AbstractString}(
     '~' => "{\\textasciitilde}",
+    '\u00A0' => "~",  # nonbreaking space
     '^' => "{\\textasciicircum}",
     '\\' => "{\\textbackslash}",
     '\'' => "{\\textquotesingle}",

src/utilities/utilities.jl

@@ -107,10 +107,10 @@ Slugify a string into a suitable URL.
 """
 function slugify(s::AbstractString)
     s = replace(s, r"\s+" => "-")
-    s = replace(s, r"^\d+" => "")
     s = replace(s, r"&" => "-and-")
     s = replace(s, r"[^\p{L}\p{P}\d\-]+" => "")
     s = strip(replace(s, r"\-\-+" => "-"), '-')
+    return s
 end
 slugify(object) = string(object) # Non-string slugifying doesn't do anything.
 

test/examples/references/latex_simple.tex

@@ -243,4 +243,15 @@ \section{\texttt{LineBreak} node}
 
 
 
+\section{Issue 2300}
+
+
+
+\label{5494601647308340695}{}
+
+
+You~Shall~Not~Break!~You~Shall~Not~Break!~You~Shall~Not~Break!
+
+
+
 \end{document}

test/examples/src.latex_simple/index.md

@@ -127,3 +127,7 @@ LaTeXEquation2(raw"""
 This sentence\
 should be over **multiple\
 lines**.
+
+## Issue 2300
+
+You Shall Not Break! You Shall Not Break! You Shall Not Break!

test/latexwriter.jl

@@ -1,6 +1,7 @@
 module LaTeXWriterTests
 
 using Test
+import Documenter
 import Documenter.LaTeXWriter
 
 @testset "file ordering" begin
@@ -32,4 +33,39 @@ import Documenter.LaTeXWriter
     ]
 end
 
+
+function _dummy_lctx()
+    doc = Documenter.Document()
+    buffer = IOBuffer()
+    return LaTeXWriter.Context(buffer, doc)
+end
+
+function _latexesc(str)
+    lctx = _dummy_lctx()
+    LaTeXWriter.latexesc(lctx, str)
+    return String(take!(lctx.io))
+end
+
+function _md_to_latex(mdstr)
+    lctx = _dummy_lctx()
+    ast = Documenter.mdparse(mdstr; mode=:single)[1]
+    LaTeXWriter.latex(lctx, ast.children)  # should use latexesc internally
+    return String(take!(lctx.io))
+end
+
+
+@testset "latex escapes" begin
+
+    md = "~ Ref.\u00A0[1], O'Reilly, \"Book #1\""
+    tex = "{\\textasciitilde} Ref.~[1], O{\\textquotesingle}Reilly, {\\textquotedbl}Book \\#1{\\textquotedbl}"
+    @test _latexesc(md) == tex
+    @test _md_to_latex(md) == tex
+
+    md = "[DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl#readme)"
+    tex = "\\href{https://github.com/JuliaDocs/DocumenterCitations.jl\\#readme}{DocumenterCitations.jl}"
+    @test _md_to_latex(md) == tex
+
+end
+
+
 end

test/utilities.jl

@@ -706,6 +706,37 @@ end
         @test remove_common_backtrace([1,2,3], [1,2,3]) == []
         @test remove_common_backtrace([1,2,3], [0,1,2,3]) == []
     end
+
+    @testset "slugify" begin
+        for (test, answer) in [
+            # Nonstrings get converted to strings
+            1 => "1",
+            # Good strings stay good
+            "a" => "a",
+            "my-heading" => "my-heading",
+            "documenter.jl/abc" => "documenter.jl/abc",
+            "https://documenter.jl/abc" => "https://documenter.jl/abc",
+            "2nd" => "2nd",
+            "2nd-2" => "2nd-2",
+            "123" => "123",
+            "123a" => "123a",
+            # Spaces get replaced by -
+            "2nd feature" => "2nd-feature",
+            # & gets replaced by -and-
+            "a & b" => "a-and-b",
+            # Multiple -- are reduced
+            "a---b" => "a-b",
+            # Leading and trailing - are stripped
+            "-a---b-" => "a-b",
+            # A combination of things
+            "   a & b" => "a-and-b",
+            "--a & b" => "a-and-b",
+            # Non letter, punctuation, digit, or `-` characters are removed
+            "a\0a" => "aa"
+        ]
+            @test Documenter.slugify(test) == answer
+        end
+    end
 end
 
 end