Add documentation task to CI

Before now, documentation build errors would only be caught when testing
manually or PRing a new version of StyledStrings.jl to the main Julia
repo.

To address this, a new CI task is introduced, and a few small changes
made to make automated docs builds possible, namely:
- Tweaking the documentation workflow
- Introducing some docs build scripts under docs/
- Fixing a dodgy jldoctest

We also add a documentation page for the internals.

.github/workflows/CI.yml

@@ -43,21 +43,18 @@ jobs:
           files: lcov.info
   docs:
     name: Documentation
-    runs-on: ubuntu-latest
     permissions:
       contents: write
+      statuses: write
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1
         with:
-          version: '1'
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
+          version: 'nightly'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
-          julia --project=docs -e '
-            using Documenter: DocMeta, doctest
-            using StyledStrings
-            DocMeta.setdocmeta!(StyledStrings, :DocTestSetup, :(using StyledStrings); recursive=true)
-            doctest(StyledStrings)'
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -1,5 +1,5 @@
 *.jl.*.cov
 *.jl.cov
 *.jl.mem
-/Manifest.toml
+**/Manifest.toml
 /docs/build/

docs/Makefile

@@ -0,0 +1,2 @@
+all:
+	julia --color=yes make.jl

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+StyledStrings = "f489334b-da3d-4c2e-b8f0-e476e12c162b"

docs/make.jl

@@ -0,0 +1,19 @@
+using StyledStrings
+using Documenter
+
+DocMeta.setdocmeta!(StyledStrings, :DocTestSetup, :(using StyledStrings); recursive=true)
+
+makedocs(;
+    modules = [StyledStrings],
+    sitename = "Styled Strings",
+    authors = "tecosaur <[email protected]> and contributors",
+    repo = "https://github.com/JuliaLang/StyledStrings.jl/blob/{commit}{path}#{line}",
+    format = Documenter.HTML(),
+    pages = [
+        "StyledStrings" => "index.md",
+        "Internals" => "internals.md",
+    ],
+    warnonly = [:cross_references],
+)
+
+deploydocs(repo="github.com/JuliaLang/StyledStrings.jl")

docs/src/index.md

@@ -184,4 +184,7 @@ StyledStrings.@styled_str
 StyledStrings.Face
 StyledStrings.addface!
 StyledStrings.SimpleColor
+Base.parse
+Base.tryparse
+Base.merge
 ```

docs/src/internals.md

@@ -0,0 +1,27 @@
+# Internals
+
+Everything documented in this page is internal and subject to breaking changes,
+even in minor version updates of Julia or StyledStrings.jl. If you are curious
+about the internals, read on, but if you want to depend on them, please consider
+opening a pull request or issue to discuss making them part of the public API.
+
+```@docs
+StyledStrings.ANSI_4BIT_COLORS
+StyledStrings.FACES
+StyledStrings.HTML_BASIC_COLORS
+StyledStrings.Legacy.ANSI_256_COLORS
+StyledStrings.Legacy.RENAMED_COLORS
+StyledStrings.Legacy.legacy_color
+StyledStrings.Legacy.load_env_colors!
+StyledStrings.ansi_4bit_color_code
+StyledStrings.eachregion
+StyledStrings.face!
+StyledStrings.getface
+StyledStrings.loadface!
+StyledStrings.loaduserfaces!
+StyledStrings.resetfaces!
+StyledStrings.termcolor
+StyledStrings.termcolor24bit
+StyledStrings.termcolor8bit
+StyledStrings.withfaces
+```

src/regioniterator.jl

@@ -27,8 +27,8 @@ an iterator which provides each substring and the applicable annotations as a
 
 # Examples
 
-```jldoctest; setup = :(import AnnotatedString; import StyledStrings.eachregion)
-julia> collect(eachregion(Base.AnnotatedString(
+```jldoctest
+julia> collect(StyledStrings.eachregion(Base.AnnotatedString(
            "hey there", [(1:3, :face => :bold), (5:9, :face => :italic)])))
 3-element Vector{Tuple{SubString{String}, Vector{Pair{Symbol, Any}}}}:
  ("hey", [:face => :bold])