Add tests

.github/workflows/CI.yml

@@ -0,0 +1,162 @@
+name: CI
+on:
+  push:
+    branches:
+      - master
+      - dev
+      - 'release-*'
+    tags:
+      - '*'
+  pull_request:
+    branches:
+      - master
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Test ${{ matrix.title }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - title: 'Linux - Latest'
+            os: ubuntu-latest
+            version: '1'
+          - title: 'Windows - Latest'
+            os: windows-latest
+            version: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+      - uses: julia-actions/cache@v1
+      - name: "Instantiate test environment"
+        shell: julia --color=yes --project=test {0}
+        run: |
+          import Pkg
+          Pkg.develop(path=".")
+          Pkg.develop(url="https://github.com/JuliaDocs/DocInventories.jl")
+          Pkg.instantiate()
+      - name: "Run tests"
+        shell: julia --color=yes --project=test --code-coverage="@" --depwarn="yes" --check-bounds="yes" {0}
+        run: |
+          include(joinpath(pwd(), "test", "runtests.jl"))
+      - name: "Summarize coverage"
+        run: julia --project=test -L devrepl.jl -e 'display(show_coverage())'
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v3
+        with:
+          files: lcov.info
+  testoldest:
+    name: Test Lower Compat Bounds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: 1.6
+      - uses: julia-actions/cache@v1
+      - name: "Instantiate test environment"
+        shell: julia --color=yes --project=test {0}
+        run: |
+          import Pkg
+          Pkg.develop(path=".")
+          Pkg.develop(url="https://github.com/JuliaDocs/DocInventories.jl")
+          Pkg.precompile()
+          Pkg.status()
+      - name: "Run tests"
+        shell: julia --color=yes --project=test {0}
+        run: |
+          include(joinpath(pwd(), "test", "runtests.jl"))
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      statuses: write
+      pages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: "Instantiate build environment"
+        shell: julia --color=yes --project=test {0}
+        run: |
+          import Pkg
+          Pkg.develop(path=".")
+          Pkg.develop(url="https://github.com/JuliaDocs/DocInventories.jl")
+          Pkg.instantiate()
+      - name: "Build documentation"
+        run: julia --project=test docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - uses: actions/upload-artifact@v3
+        with:
+          name: documenter-interlinks-docs
+          path: docs/build/
+  codestyle:
+    name: Codestyle
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Install JuliaFormatter and format
+        # This will use the latest version by default but you can set the version like so:
+        #
+        # julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter", version="0.13.0"))'
+        shell: julia {0}
+        run: |
+          using Pkg
+          Pkg.add(PackageSpec(name="JuliaFormatter"))
+          using JuliaFormatter
+          format(["src", "docs", "test", "devrepl.jl"], verbose=true)
+      - name: Format Check
+        shell: julia {0}
+        run: |
+          out = Cmd(`git diff -U0`) |> read |> String
+          if out == ""
+              exit(0)
+          else
+              @error "Some files have not been formatted !!!\n\n$out"
+              exit(1)
+          end
+      - name: Spell Check
+        uses: crate-ci/typos@master
+      - name: Version Check
+        shell: julia {0}
+        run: |
+          using Pkg
+          VERSION = VersionNumber(Pkg.TOML.parsefile("Project.toml")["version"])
+          BRANCH = ENV["GITHUB_REF_NAME"]
+          if ENV["GITHUB_EVENT_NAME"] == "pull_request"
+              # For pull_request events, return the head (aka., "from") branch,
+              # not the base (aka., "to") branch.
+              BRANCH = ENV["GITHUB_HEAD_REF"]
+          end
+          if startswith(BRANCH, "release-")
+              if (length(VERSION.prerelease) == length(VERSION.build))
+                  println("Version $VERSION on release branch OK")
+              else
+                  @error "Invalid version $VERSION on release branch"
+                  exit(1)
+              end
+          elseif (ENV["GITHUB_REF_TYPE"] == "branch") && (BRANCH != "master")
+              if ("dev" in VERSION.prerelease) || ("dev" in VERSION.build)
+                  println("Version $VERSION OK with dev-suffix on $BRANCH")
+              else
+                  @error "Invalid version $VERSION on branch $BRANCH: must contain dev suffix"
+                  exit(1)
+              end
+          else
+              println("Version $VERSION OK on $BRANCH")
+          end
+          exit(0)

.github/workflows/ClearPreview.yml

@@ -0,0 +1,26 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
+        env:
+            PRNUM: ${{ github.event.number }}

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

README.md

@@ -2,6 +2,8 @@
 
 A plugin for [Documenter.jl](https://documenter.juliadocs.org/) that enables linking between projects.
 
+**WARNING: This is a prototype. If you use this package pre-1.0, be prepared to having to adapt to breaking changes at any time.**
+
 Loading `DocumenterInterLinks` in `Docs/make.jl` causes Documenter to produce an "inventory file" `objects.inv` in the output folder, which should get deployed together with the documentation. This file contains a mapping from names to URLs for all link targets in the documentation.
 
 Other projects may use this inventory file to resolve `@extref` links, see [External Citations](#external-citations).

src/expand_extrefs.jl

@@ -38,26 +38,31 @@ function expand_extrefs!(doc::Documenter.Document, page, mdast::MarkdownAST.Node
             end
             node
         else
-            expand_extref(doc, node, page, links)
+            expand_extref(doc, node, page.source, links)
         end
     end
 end
 
 
 function expand_extref(
-    doc::Documenter.Document,
+    doc::Union{Nothing,Documenter.Document},
     node::MarkdownAST.Node,
-    page,
-    links::InterLinks
+    source::String,
+    links::InterLinks;
+    quiet=false
 )
     (node.element isa MarkdownAST.Link) || return node
     startswith(lowercase(node.element.destination), "@extref") || return node
     extref = node.element.destination
     m = match(links.rx, extref)
     if isnothing(m)
-        msg = "On $(page.source), invalid @extref $(repr(extref)). Should be \"@extref [[inventory] [[:domain][:role]:]name]\"."
-        @error msg node
-        push!(doc.internal.errors, :external_cross_references)
+        if !quiet
+            msg = "On $(repr(source)), invalid @extref $(repr(extref)). Should be \"@extref [[inventory] [[:domain][:role]:]name]\"."
+            @error msg node
+        end
+        if !isnothing(doc)
+            push!(doc.internal.errors, :external_cross_references)
+        end
         node.element.destination = ""
         # We clear the link destination to remove the link from
         # consideration in Documenter.crossref or the link checker.
@@ -70,14 +75,18 @@ function expand_extref(
         try
             node.element.destination = find_in_interlinks(links, extref)
         catch exc
-            msg = "On $(page.source), cannot resolve external link: "
-            if exc isa Union{ArgumentError,InventoryItemNotFoundError}
-                msg *= exc.msg
-            else
-                msg *= sprint(showerror, exc)
+            if !quiet
+                msg = "On $(repr(source)), cannot resolve external link: "
+                if exc isa Union{ArgumentError,InventoryItemNotFoundError}
+                    msg *= exc.msg
+                else
+                    msg *= sprint(showerror, exc)
+                end
+                @error msg node # exception=(exc, catch_backtrace())
+            end
+            if !isnothing(doc)
+                push!(doc.internal.errors, :external_cross_references)
             end
-            @error msg node # exception=(exc, catch_backtrace())
-            push!(doc.internal.errors, :external_cross_references)
             node.element.destination = ""
         end
     end