Add documentation

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

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

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 `<title>` tag, unless specified in the `.pages` option.
 2. If the first heading is interpreted as being the page title, it is not displayed
    in the navigation sidebar.
+
+# Inventory
+
+The `HTMLWriter` automatically generates an `objects.inv` "inventory" file in
+the output `build` folder. This file contains a list of all pages, headers and
+docstrings in the documentation, and a relative URL that can be used to link to
+those items from an external source.
+
+Other projects that build their documentation with Documenter can use the
+[`DocumenterInterLinks` plugin](https://github.com/JuliaDocs/DocumenterInterLinks.jl#readme)
+to link to any other project with an inventory file, see
+[External Cross-References](@ref).
+
+The [format of the `objects.inv` file](https://juliadocs.org/DocInventories.jl/stable/formats/#Sphinx-Inventory-Format)
+is borrowed from the [Sphinx project](https://www.sphinx-doc.org/en/master/). It consists
+of a plain text header that includes the project name, taken from the `sitename` argument
+to [`Documenter.makedocs`](@ref), and a project `version` (currently empty).
+The bulk of the file is a list of plain text records, compressed with gzip. See
+[Inventory Generation](http://juliadocs.org/DocumenterInterLinks.jl/stable/write_inventory/)
+for details on these records.
 """
 module HTMLWriter