Add inventory writing (#249)

Author: goerz

Project.toml

@@ -6,20 +6,24 @@ version = "0.1.12"
 [deps]
 ANSIColoredPrinters = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 NodeJS_20_jll = "c7aee132-11e1-519c-8219-0a43005e73c2"
 REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
 ANSIColoredPrinters = "0.0.1"
+DocInventories = "1.0"
 DocStringExtensions = "0.9"
 Documenter = "1"
 DocumenterCitations = "1"
 IOCapture = "0.2"
 NodeJS_20_jll = "20"
+TOML = "1.0.3"
 julia = "1.6"
 
 [weakdeps]

src/writer.jl

@@ -1,5 +1,7 @@
 import Documenter: Documenter, Builder, Expanders, MarkdownAST
 import Documenter.DOM: escapehtml
+using DocInventories: DocInventories, Inventory, InventoryItem
+using TOML: TOML
 
 import ANSIColoredPrinters
 using Base64: base64decode, base64encode
@@ -68,6 +70,8 @@ Base.@kwdef struct MarkdownVitepress <: Documenter.Writer
     deploy_decision::Union{Nothing, Documenter.DeployDecision} = nothing
     "A list of assets, the same as what is provided to Documenter's HTMLWriter."
     assets = nothing
+    "A version string to write to the header of the objects.inv inventory file. This should be a valid version number without a v prefix. Defaults to the version defined in the Project.toml file in the parent folder of the documentation root"
+    inventory_version::Union{String,Nothing} = nothing
 end
 
 # return the same file with the extension changed to .md
@@ -181,8 +185,8 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi
     end
     # Documenter.jl wants assets in `assets/`, but Vitepress likes them in `public/`,
     # so we rename the folder.
+    mkpath(joinpath(builddir, settings.md_output_path, "public"))
     if isdir(joinpath(sourcedir, "assets")) && !isdir(joinpath(sourcedir, "public"))
-        mkpath(joinpath(builddir, settings.md_output_path, "public"))
         files = readdir(joinpath(builddir, settings.md_output_path, "assets"); join = true)
         logo_files = contains.(last.(splitdir.(files)), "logo")
         favicon_files = contains.(last.(splitdir.(files)), "favicon")
@@ -211,14 +215,30 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi
     # This needs to be run after favicons and logos are moved to the public subfolder
     modify_config_file(doc, settings, deploy_decision)
 
+    version = settings.inventory_version
+    if isnothing(version)
+        project_toml = joinpath(dirname(doc.user.root), "Project.toml")
+        version = _get_inventory_version(project_toml)
+    end
+    inventory = Inventory(; project=doc.user.sitename, version)
+
     # Iterate over the pages, render each page separately
     for (src, page) in doc.blueprint.pages
         # This is where you can operate on a per-page level.
         open(docpath(page.build, builddir, settings.md_output_path), "w") do io
             for node in page.mdast.children
-                render(io, mime, node, page, doc)
+                render(io, mime, node, page, doc; inventory)
             end
         end
+        item = InventoryItem(
+            name = replace(splitext(src)[1], "\\" => "/"),
+            domain = "std",
+            role = "doc",
+            dispname = _pagetitle(page),
+            priority = -1,
+            uri = _get_inventory_uri(doc, page, nothing)
+        )
+        push!(inventory, item)
     end
 
     mkpath(joinpath(builddir, "final_site"))
@@ -228,6 +248,9 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi
         touch(config_path)
     end
 
+    objects_inv = joinpath(builddir, settings.md_output_path, "public", "objects.inv")
+    DocInventories.save(objects_inv, inventory)
+
     # Now that the Markdown files are written, we can build the Vitepress site if required.
     if settings.build_vitepress
         @info "DocumenterVitepress: building Vitepress site."
@@ -352,7 +375,8 @@ function render(io::IO, mime::MIME"text/plain", vec::Vector, page, doc; kwargs..
 end
 
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, anchor::Documenter.Anchor, page, doc; kwargs...)
-    println(io, "\n<a id='", lstrip(Documenter.anchor_fragment(anchor), '#'), "'></a>")
+    anchor_id = lstrip(Documenter.anchor_fragment(anchor), '#')
+    println(io, "\n<a id='", anchor_id, "'></a>")
     return render(io, mime, node, anchor.object, page, doc; kwargs...)
 end
 
@@ -381,8 +405,17 @@ end
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, docs::Documenter.DocsNode, page, doc; kwargs...)
     open_txt = get(page.globals.meta, :CollapsedDocStrings, false) ? "" : "open"
     anchor_id = sanitized_anchor_label(docs.anchor)
+    category = Documenter.doccat(docs.object)
+    if haskey(kwargs, :inventory)
+        item = InventoryItem(
+            name = docs.anchor.id,
+            role = lowercase(category),
+            uri = _get_inventory_uri(doc, page, anchor_id),
+        )
+        push!(kwargs[:inventory], item)
+    end
     # Docstring header based on the name of the binding and it's category.
-    _badge_text = """<Badge type="info" class="jlObjectType jl$(Documenter.doccat(docs.object))" text="$(Documenter.doccat(docs.object))" />"""
+    _badge_text = """<Badge type="info" class="jlObjectType jl$(category)" text="$(category)" />"""
     print(io ,"""<details class='jldocstring custom-block' $(open_txt)>
     <summary><a id='$(anchor_id)' href='#$(anchor_id)'><span class="jlbinding">$(docs.object.binding)</span></a> $(_badge_text)</summary>\n
     """)
@@ -892,16 +925,25 @@ end
 # Headers
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, header::Documenter.AnchoredHeader, page, doc; kwargs...)
     anchor = header.anchor
-    id = sanitized_anchor_label(anchor)
+    id = replace(sanitized_anchor_label(anchor), " " => "-")  # potentially use MarkdownAST.mdflatten here?
     heading = first(node.children)
     println(io)
     print(io, "#"^(heading.element.level), " ")
     heading_iob = IOBuffer()
     render(heading_iob, mime, node, heading.children, page, doc; kwargs...)
     heading_text = rstrip(String(take!(heading_iob)))
     print(io, heading_text)
-    if id != heading_text # if a custom ID is set, then use it.
-        print(io, " {#$(replace(id, " " => "-"))}") # potentially use MarkdownAST.mdflatten here?
+    print(io, " {#$(id)}")
+    if haskey(kwargs, :inventory)
+        item = InventoryItem(
+            name = header.anchor.id,
+            domain = "std",
+            role = "label",
+            dispname = _get_inventory_dispname(header.anchor.id, Documenter.MDFlatten.mdflatten(anchor.node)),
+            priority = -1,
+            uri = _get_inventory_uri(doc, page, id),
+        )
+        push!(kwargs[:inventory], item)
     end
     println(io)
 end
@@ -1094,3 +1136,83 @@ function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Nod
     println(io)
     println(io, "![]($image_path)")
 end
+
+
+function _get_inventory_version(project_toml)
+    version = ""
+    if isfile(project_toml)
+        project_data = TOML.parsefile(project_toml)
+        if haskey(project_data, "version")
+            version = project_data["version"]
+            @info "Automatic `version=$(repr(version))` for inventory from $(relpath(project_toml))"
+        else
+            @warn "Cannot extract version for inventory from $(project_toml): no version information"
+        end
+    else
+        @warn "Cannot extract version for inventory from $(project_toml): no such file"
+    end
+    if isempty(version)
+        # The automatic `inventory_version` determined in this function is intended only for
+        # projects with a standard layout with Project.toml file in the expected
+        # location (the parent folder of doc.user.root). Any non-standard project should
+        # explicitly set an `inventory_version` as an option to `MarkdownVitepress()` in `makedocs`, or
+        # specifically set `inventory_version=""` so that `_get_inventory_version` is never
+        # called, and thus this warning is suppressed.
+        @warn "Please set `inventory_version` in the `MarkdownVitepress()` options passed to `makedocs`."
+    end
+    return version
+end
+
+
+function _get_inventory_uri(doc, page, anchor_id)
+    filename = relpath(page.build, doc.user.build)
+    page_url = splitext(filename)[1]
+    if Sys.iswindows()
+        page_url = replace(page_url, "\\" => "/")
+    end
+    uri = join(map(_escapeuri, split(page_url, "/")), "/")
+    if !isnothing(anchor_id)
+        uri = uri * "#" * _escapeuri(anchor_id)
+    end
+    return uri
+end
+
+
+function _get_inventory_dispname(name, dispname)
+    if dispname == name
+        dispname = "-"
+    end
+    return dispname
+end
+
+
+function _pagetitle(page)
+    page_mdast = page.mdast
+    @assert page_mdast.element isa MarkdownAST.Document
+    title_node = nothing
+    for node in page_mdast.children
+        # AnchoredHeaders should have just one child node, which is the Heading node
+        if isa(node.element, Documenter.AnchoredHeader)
+            node = first(node.children)
+        end
+        if isa(node.element, MarkdownAST.Heading) && node.element.level == 1
+            title_node = collect(node.children)
+            break
+        end
+    end
+    if isnothing(title_node)
+        return "-"
+    else
+        return Documenter.MDFlatten.mdflatten(title_node)
+    end
+end
+
+
+@inline _issafe(c::Char) =
+    c == '-' || c == '.' || c == '_' || (isascii(c) && (isletter(c) || isnumeric(c)))
+
+_utf8_chars(str::AbstractString) = (Char(c) for c in codeunits(str))
+
+_escapeuri(c::Char) = string('%', uppercase(string(Int(c), base = 16, pad = 2)))
+_escapeuri(str::AbstractString) =
+    join(_issafe(c) ? c : _escapeuri(c) for c in _utf8_chars(str))