diff --git a/docs/src/man/guide.md b/docs/src/man/guide.md index 3b932cd604..a38dcfbde0 100644 --- a/docs/src/man/guide.md +++ b/docs/src/man/guide.md @@ -304,6 +304,36 @@ This also works across different pages in the same way. Note that these sections docstrings must be unique within a document. +## External Cross-References + +Any project building its documentation with the most recent release of Documenter will +generate an [`objects.inv` inventory](https://juliadocs.org/DocInventories.jl/stable/formats/#Sphinx-Inventory-Format) +that can be found in the root of the [deployed documentation](@ref Hosting-Documentation). +The [`DocumenterInterLinks` plugin](https://github.com/JuliaDocs/DocumenterInterLinks.jl#readme) +allows to define a mapping in your `make.jl` file between an external project name +and its inventory file, e.g., + +```julia +using DocumenterInterLinks + +links = InterLinks( + "Documenter" => "https://documenter.juliadocs.org/stable/objects.inv" +) +``` + +That `InterLinks` object should then be passed to [`makedocs`](@ref) as an element of +`plugins`. This enables the ability to cross-reference into the external documentation, +e.g., of the `Documenter` package, using an [`@extref` link](@ref) with a syntax similar +to the above [`@ref`](@ref Cross-Referencing), e.g., + +```markdown +See the [`Documenter.makedocs`](@extref) function. +``` + +See the [documentation of the `DocumenterInterLinks` package](http://juliadocs.org/DocumenterInterLinks.jl/stable/) +for more details. + + ## Navigation Documenter can auto-generate tables of contents and docstring indexes for your document with diff --git a/docs/src/man/syntax.md b/docs/src/man/syntax.md index 4989186cc5..7f56dd0ccd 100644 --- a/docs/src/man/syntax.md +++ b/docs/src/man/syntax.md @@ -268,6 +268,18 @@ document more than once is disallowed. Both user-defined and internally generated header reference labels take precedence over docstring references, in case there is a conflict. +### `@extref` link + +Using the [`DocumenterInterLinks` plugin](https://github.com/JuliaDocs/DocumenterInterLinks.jl#readme), +it is possible to cross-reference the documentation of other projects whose documentation +is generated by Documenter or [Sphinx](https://www.sphinx-doc.org/en/master/), using +`@extref` links similar to the built-in `@ref` links for internal references. + +See [External Cross-References](@ref) and the +[documentation of the `DocumenterInterLinks` package](http://juliadocs.org/DocumenterInterLinks.jl/stable/) +for more details. + + ## `@meta` block This block type is used to define metadata key/value pairs that can be used elsewhere in the diff --git a/src/html/HTMLWriter.jl b/src/html/HTMLWriter.jl index 3e9bacf9ef..67b32322b1 100644 --- a/src/html/HTMLWriter.jl +++ b/src/html/HTMLWriter.jl @@ -11,7 +11,8 @@ keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_link `prettyurls`, `collapselevel`, `sidebar_sitename`, `highlights`, `mathengine` and `footer`. **`sitename`** is the site's title displayed in the title bar and at the top of the -*navigation menu. This argument is mandatory for [`HTMLWriter`](@ref). +*navigation menu. It is also written into the inventory (see below). +This argument is mandatory for [`HTMLWriter`](@ref). **`pages`** defines the hierarchy of the navigation menu. @@ -37,6 +38,26 @@ then it is intended as the page title. This has two consequences: and in the `