feat: link references to symbols documented elsewhere (input tagfiles) - #1267
Open
gennaroprota wants to merge 1 commit into
Open
feat: link references to symbols documented elsewhere (input tagfiles)#1267gennaroprota wants to merge 1 commit into
gennaroprota wants to merge 1 commit into
Conversation
MrDocs can now read external tagfiles and, thus, have a doc comment that references a symbol not extracted by MrDocs itself. A new option, `input-tagfiles`, specifies the external tagfile and maps each one to the base URL its documentation set is published under. A reference that resolves to nothing in the corpus takes its URL from there instead of rendering as plain code. The name is resolved from the scope it is written in outward, as any other reference is, and is never shortened to reach an entry. Every generator takes the URL from one place. Tagfiles are read with a small ad-hoc parser, rather than by LibXml2: the format is a small, machine-generated subset of XML, and linking LibXml2 into mrdocs-core would make it a dependency of every build and of every consumer of the installed package. A path that cannot be read, or a file that is not a tagfile, fails the build. The option MrDocs already had for writing a tagfile (named `tagfile`) becomes `output-tagfile`, so that the pair of options says which direction each of them goes; `tagfile` remains as a deprecated alias. Note that all deprecated options warn now, including `report`, which didn't before.
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1267 +/- ##
========================================
Coverage 83.12% 83.12%
========================================
Files 35 35
Lines 3662 3662
Branches 844 844
========================================
Hits 3044 3044
Misses 410 410
Partials 208 208
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
An automated preview of the documentation is available at https://1267.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-28 17:48:24 UTC |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
MrDocs can now read external tagfiles and, thus, have a doc comment that references a symbol not extracted by MrDocs itself. A new option,
input-tagfiles, specifies the external tagfile and maps each one to the base URL its documentation set is published under. A reference that resolves to nothing in the corpus takes its URL from there instead of rendering as plain code. The name is resolved from the scope it is written in outward, as any other reference is, and is never shortened to reach an entry. Every generator takes the URL from one place.Tagfiles are read with a small ad-hoc parser, rather than by LibXml2: the format is a small, machine-generated subset of XML, and linking LibXml2 into mrdocs-core would make it a dependency of every build and of every consumer of the installed package.
A path that cannot be read, or a file that is not a tagfile, fails the build.
The option MrDocs already had for writing a tagfile (named
tagfile) becomesoutput-tagfile, so that the pair of options says which direction each of them goes;tagfileremains as a deprecated alias. Note that all deprecated options warn now, includingreport, which didn't before.Changes
input-tagfilesoption and loading it into the corpus;Corpus::externalUrlbesideCorpus::lookup;hrefonReferenceInlineand the branch that renders it; thetagfile->output-tagfilerename with a deprecated alias; generic, deferred reporting of deprecated options.clang.mrdocs.TagfileIndex,clang.mrdocs.TagfileReader).config/input-tagfilesfixture (xml, adoc, html) covering a fully qualified name, a name relative to its enclosing scope, a namespace page, a member with an anchor, a member on its own page, and names that resolve to nothing; theconfig/tagfilefixture is renamed toconfig/output-tagfileand regenerated for its new file names.ConfigOptions.json, so the generatedconfig schema and the published option reference change; the new
hreffield regenerates the reflected DOM schema (mrdocs.rng,generators/mrdocs.schema.json,dom-schema.adoc).--tagfilenow pass pass--output-tagfile.tagfilestill works but warns. The long-deprecatedreportoption starts warning too. Underwarn-as-error, either fails the build.Testing
The unit suites test the index and the reader, including the inputs it must reject; the golden fixture tests resolution end to end in XML, AsciiDoc and HTML.
Beyond that, the reader was validated against the real Cppreference tagfile, and the possibility to repeat
--input-tagfiles=<path>=<base-url>, needed by the Antora extension, was checked by hand.Documentation
The "External docs" section of configuration/output.adoc documents the new option with an example. commands/inlines.adoc cross-references it from
@ref, and the option reference is generated fromConfigOptions.json. No new page is added.