Inventory Generation
The inventory files that get loaded into InterLinks
should be automatically created by a project's documentation generator.
- The Sphinx documentation generator used by most Python packages automatically creates an
objects.inv
inventory file in the root of every HTML build. - For Julia projects that build their documentation with
Documenter
≥ v1.3
, anobjects.inv
inventory file in the same format is automatically created in thedocs/build/
folder. DocumenterInventoryWritingBackport.jl
backports the automatic inventory writing to older versions ofDocumenter
(≥ v0.25
). This package simply needs to be loaded in a project'sdocs/make.jl
file.- Any package loading
DocumenterInterLinks
indocs/make.jl
also gets theDocumenterInventoryWritingBackport
automatically.
The inventory file should be deployed together with the rest of the documentation, so that it is accessible to other projects. When a project does not use a documentation generator that writes an inventory file, it may be possible to maintain an inventory by hand. See also the Wiki for a collection of inventory files for Julia and other projects.
For a Documenter-based project, the automatic inventory contains:
- An entry for every docstring included in the documentation. These use the ad-hoc
jl
domain and arole
that depends on the object. - An entry for every section heading. To ensure compatibility with Sphinx, these entries use the
std
domain, thelabel
role, a slugified version of the heading (or the explicit header@id
) as aname
, and the full heading (stripped of formatting, but including spaces) as thedispname
. - An entry for every page in the documentation. These use the
std
domain and thedoc
role. The name is the path (with Unix-style forward-slash path separators) of the.md
file from which the page was generated, without the.md
extension. This should correspond to the relative URI of the resulting page, excluding a final slash or an.html
extension.
The Julia Domain
You probably will not need to worry about the information in this section.
The inventory for a Documenter
-based documentation includes entries for docstrings using an ad-hoc jl
domain. The role
for each entry matches how Documenter
identifies the underlying object with Documenter.doccat
. You will find this identification as part of how the docstring shows in the documentation; for example, note the "— Type" in the header of DocumenterInterLinks.InterLinks
. The role
that will be written to the inventory is simply the lowercase string of this identification. Currently, Documenter
uses the following:
- "Macro" (role
macro
): for macros. For example,":jl:macro:`Base.@inbounds`"
forBase.@inbounds
. - "Keyword" (role
keyword
): for Julia keywords (used in the documentation of the Julia language itself, only). For example,":jl:keyword:`if`"
for theif
keyword. - "Function" (role
function
): for functions. For example,":jl:function:`Statistics.mean`"
forStatistics.mean
. - "Method" (role
method
): for methods of functions. This is used when there is a docstring for a specific tuple of argument types. For example,":jl:method:`Base.:*-Tuple{AbstractMatrix, AbstractMatrix}`"
for the*
operator of two matrices. - "Type" (role
type
): For types, both structs and abstract types. For example,":jl:type:`Base.AbstractMatrix`"
forAbstractMatrix
. - "Module" (role
module
): For modules. For example,":jl:module:`LinearAlgebra.BLAS`"
forLinearAlgebra.BLAS
. - "Constant" (role
constant
): For documented data / constants inside a module. For example,":jl:constant:`Base.VERSION`"
for Julia'sVERSION
constant.
As discussed in Syntax, the domain and roles are for disambiguation only. In practice, the above example references might be written as
* [`Base.@inbounds`](@extref)
* [the `if` keyword](@extref Julia `if`)
* [`Statistics.mean`](@extref)
* [`*` operator of two matrices](@extref `Base.:*-Tuple{AbstractMatrix, AbstractMatrix}`)
* [`LinearAlgebra.BLAS`](@extref)
* [Julia's `VERSION` constant](@extref `Base.VERSION`)
These render as:
Leaving out the project name Julia
in all but the second item is recommended only if Julia
is the first project in the InterLinks
object.