diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 3d33cb9..4035085 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-04T21:49:35","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-05T02:58:30","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/api/internals/index.html b/dev/api/internals/index.html index 9d0fccc..910a670 100644 --- a/dev/api/internals/index.html +++ b/dev/api/internals/index.html @@ -1,5 +1,5 @@ -Internals · DocumenterInterLinks.jl
GitHub

Internals

DocumenterInterLinks.InterLinks — Type

Plugin for enabling external links in Documenter.jl.

links = InterLinks(
+Internals · DocumenterInterLinks.jl
GitHub
Internals
DocumenterInterLinks.InterLinks — Type
Plugin for enabling external links in Documenter.jl.
links = InterLinks(
     "project1" => "https://project1.url/",
     "project2" => "https://project2.url/inventory.file",
     "project3" => (
@@ -15,4 +15,4 @@
     "https://documenter.juliadocs.org/stable/",
     "https://documenter.juliadocs.org/stable/inventory.toml.gz",
     joinpath(@__DIR__, "src", "interlinks", "Documenter.toml")
-)
The first reachable inventory file will be used. This enables, e.g., to define a local inventory file as a fallback in case the online inventory file location is unreachable, as in the last example.
  • A DocInventories.Inventory instance.
    • Properties
    • names: A list of project names
    • inventories: A dictionary of project names to DocInventories.Inventory instances
    • rx: a Regex that matches any valid @extref expression that can be resolved.
    The InterLinks object also acts as a (read-only) ordered dictionary so that, e.g., links["project1"] returns the DocInventories.Inventory for that project.
    Search
    Free-form search in a particular inventory is possible with, e.g.,
    links["Julia"](search)
    See the discussion on search in the DocInventories.Inventory documentation. Such a search returns a list of matching DocInventories.InventoryItem instances.
    In addition,
    links(search)
    allows to search across all inventories. This returns a list of @extref strings that could be used to reference the matching items.
    Methods
    See also
    The InterLinks mapping is deliberately reminiscent of the intersphinx_mapping setting in Sphinx.
    source
    DocumenterInterLinks.find_in_interlinks — Method
    Find an @extref link in any of the InterLinks inventories.
    url = find_in_interlinks(links, extref)
    finds extref in links and returns the full URL that resolves the link.
    Arguments
    • links: the [InterLinks] instance to resolve the reference in
    • extref: a string of the form  "@extref [inventory] [[:domain][:role]:]name"
    source
    
+)

    The first reachable inventory file will be used. This enables, e.g., to define a local inventory file as a fallback in case the online inventory file location is unreachable, as in the last example.

  • A DocInventories.Inventory instance.

    • Properties

    • names: A list of project names
    • inventories: A dictionary of project names to DocInventories.Inventory instances
    • rx: a Regex that matches any valid @extref expression that can be resolved.

    The InterLinks object also acts as a (read-only) ordered dictionary so that, e.g., links["project1"] returns the DocInventories.Inventory for that project.

    Search

    Free-form search in a particular inventory is possible with, e.g.,

    links["Julia"](search)

    See the discussion on search in the DocInventories.Inventory documentation. Such a search returns a list of matching DocInventories.InventoryItem instances.

    In addition,

    links(search)

    allows to search across all inventories. This returns a list of @extref strings that could be used to reference the matching items.

    Methods

    See also

    The InterLinks mapping is deliberately reminiscent of the intersphinx_mapping setting in Sphinx.

    source
    DocumenterInterLinks.find_in_interlinks — Method

    Find an @extref link in any of the InterLinks inventories.

    url = find_in_interlinks(links, extref)

    finds extref in links and returns the full URL that resolves the link.

    Arguments

    • links: the [InterLinks] instance to resolve the reference in
    • extref: a string of the form "@extref [project] [[:domain][:role]:]name"
    source
    diff --git a/dev/howtos/index.html b/dev/howtos/index.html index bd401ec..9dfca33 100644 --- a/dev/howtos/index.html +++ b/dev/howtos/index.html @@ -49,4 +49,4 @@ "@extref matplotlib :std:doc:`index`" "@extref Documenter :std:doc:`index`" "@extref Julia :std:doc:`index`"

    These matching @extref links should be modified according to the Recommended Syntax.

    What if I want to link to a project that does not provide an inventory file?

    Inventory files really should created automatically using a documentation generator. Try to get the project to use one that produces inventory files or help them set up their documentation system so that it does.

    Until Documenter incorporates the Inventory Generation currently provided by this plugin, one may produce an inventory file for an existing Julia/Documenter-based project by cloning the project, opening a REPL so that include("docs/make.jl") successfully builds the documentation for that projects, and then repeat include("docs/make.jl") after running

    julia> ] add DocumenterInterLinks
-julia> using DocumenterInterLinks

    in the same REPL. You should then find an objects.inv in the docs/build folder. Use the DocInventories package to convert it to TOML Format. This is how the inventory files used in this documentation were generated, e.g., for the Julia project itself.

    There may be projects that legitimately do not provide inventories. For example, some simple Julia projects write out their entire documentation in their README on Github. In that case, you should either use standard links or manually create an inventory file. The easiest way to do this is to write out an inventory in TOML Format by hand.

    Documenter's markdown flavor lacks the ability for reference links. If you link to the same very long URLs repeatedly, this becomes cumbersome.

    In principle, you could manually write out an inventory file that defines link labels and their associated URLs, along the lines of the discussion in Documenter's PR #1351. Whether you should abuse DocumenterInterLinks in this way might be a matter of debate.

    A situation where I do think this makes sense is if you repeatedly link to some website with very structured content, e.g. Wikipedia or the Julia Discourse Forum. As shown in the DocInventories documentation, you could write a Wikipedia inventory file just for the articles you want to link to, and then have a link such as

    [Julia](@extref Wikipedia)

    in your documentation to link to Julia (programming language).

    +julia> using DocumenterInterLinks

    in the same REPL. You should then find an objects.inv in the docs/build folder. Use the DocInventories package to convert it to TOML Format. This is how the inventory files used in this documentation were generated, e.g., for the Julia project itself.

    There may be projects that legitimately do not provide inventories. For example, some simple Julia projects write out their entire documentation in their README on Github. In that case, you should either use standard links or manually create an inventory file. The easiest way to do this is to write out an inventory in TOML Format by hand.

    Documenter's markdown flavor lacks the ability for reference links. If you link to the same very long URLs repeatedly, this becomes cumbersome.

    In principle, you could manually write out an inventory file that defines link labels and their associated URLs, along the lines of the discussion in Documenter's PR #1351. Whether you should abuse DocumenterInterLinks in this way might be a matter of debate.

    A situation where I do think this makes sense is if you repeatedly link to some website with very structured content, e.g. Wikipedia or the Julia Discourse Forum. As shown in the DocInventories documentation, you could write a Wikipedia inventory file just for the articles you want to link to, and then have a link such as

    [Julia](@extref Wikipedia)

    in your documentation to link to Julia (programming language).

    diff --git a/dev/index.html b/dev/index.html index 16521ff..d53b1f2 100644 --- a/dev/index.html +++ b/dev/index.html @@ -43,4 +43,4 @@ uri="lib/public/#Documenter.makedocs", dispname="Documenter.makedocs" )

    We can include the domain and role in an @extref link as

    * [`makedocs`](@extref :function:`Documenter.makedocs`)
-* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)

    using a syntax that is reminiscent of the Sphinx cross-referencing syntax. The use of domains and roles in DocumenterInterLinks (unlike in Sphinx) is for disambiguation only, in case there are multiple items with the same name. In general, follow the Recommended Syntax guidelines.

    +* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)

    using a syntax that is reminiscent of the Sphinx cross-referencing syntax. The use of domains and roles in DocumenterInterLinks (unlike in Sphinx) is for disambiguation only, in case there are multiple items with the same name. In general, follow the Recommended Syntax guidelines.

    diff --git a/dev/search_index.js b/dev/search_index.js index b36c5ef..92ce2e2 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"api/internals/#Internals","page":"Internals","title":"Internals","text":"","category":"section"},{"location":"api/internals/","page":"Internals","title":"Internals","text":"Modules = [DocumenterInterLinks]","category":"page"},{"location":"api/internals/#DocumenterInterLinks.ExtCrossReferences","page":"Internals","title":"DocumenterInterLinks.ExtCrossReferences","text":"Pipeline step to expand all @extref cross-references.\n\nThis runs before Documenter.Builder.CrossReferences.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.InterLinks","page":"Internals","title":"DocumenterInterLinks.InterLinks","text":"Plugin for enabling external links in Documenter.jl.\n\nlinks = InterLinks(\n \"project1\" => \"https://project1.url/\",\n \"project2\" => \"https://project2.url/inventory.file\",\n \"project3\" => (\n \"https://project3.url/\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"inventory.file\")\n );\n default_inventory_file=\"objects.inv\"\n)\n\ninstantiates a plugin object that must be passed as an element of the plugins keyword argument to Documenter.makedocs. This then enables @extref links in the project's documentation to be resolved, see the Documentation for details.\n\nArguments\n\nThe InterLinks plugin receives mappings of project names to the project root URL and inventory locations. Each project names must be an alphanumerical ASCII string. For Julia projects, it should be the name of the package without the .jl suffix, e.g., \"Documenter\" for Documenter.jl. For Python projects, it should be the name of project's main module.\n\nThe root url / inventory location (the value of the mapping), can be given in any of the following forms:\n\nA single string with a URL of the inventory file, e.g.\n\"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\"`\nThe root URL relative which all URIs inside the inventory are taken to be relative is everything up to the final slash in the inventory URL, \"https://www.sphinx-doc.org/en/master/\" in this case.\nA single string with a project root URL, for example,\n\"sphinx\" => \"https://www.sphinx-doc.org/en/master/\",`\nwhich must end with slash. This looks for the inventory file with the name corresponding to default_inventory_file directly underneath the given root URL.\nA tuple of strings, where the first element is the project root URL and all subsequent elements are locations (URLs or local file paths) to an inventory file, e.g.,\n\"Julia\" => (\n \"https://docs.julialang.org/en/v1/\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"Julia.toml\")\n),\n\"Documenter\" => (\n \"https://documenter.juliadocs.org/stable/\",\n \"https://documenter.juliadocs.org/stable/inventory.toml.gz\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"Documenter.toml\")\n)\nThe first reachable inventory file will be used. This enables, e.g., to define a local inventory file as a fallback in case the online inventory file location is unreachable, as in the last example.\nA DocInventories.Inventory instance.\n\nProperties\n\nnames: A list of project names\ninventories: A dictionary of project names to DocInventories.Inventory instances\nrx: a Regex that matches any valid @extref expression that can be resolved.\n\nThe InterLinks object also acts as a (read-only) ordered dictionary so that, e.g., links[\"project1\"] returns the DocInventories.Inventory for that project.\n\nSearch\n\nFree-form search in a particular inventory is possible with, e.g.,\n\nlinks[\"Julia\"](search)\n\nSee the discussion on search in the DocInventories.Inventory documentation. Such a search returns a list of matching DocInventories.InventoryItem instances.\n\nIn addition,\n\nlinks(search)\n\nallows to search across all inventories. This returns a list of @extref strings that could be used to reference the matching items.\n\nMethods\n\nfind_in_interlinks(links, extref) – find the URL for an extref\n\nSee also\n\nThe InterLinks mapping is deliberately reminiscent of the intersphinx_mapping setting in Sphinx.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.WriteInventory","page":"Internals","title":"DocumenterInterLinks.WriteInventory","text":"Pipeline step to write the objects.inv inventory to the build directory.\n\nThis runs after Documenter.Builder.RenderDocument and only if Documenter was set up for HTML output.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.find_in_interlinks-Tuple{InterLinks, AbstractString}","page":"Internals","title":"DocumenterInterLinks.find_in_interlinks","text":"Find an @extref link in any of the InterLinks inventories.\n\nurl = find_in_interlinks(links, extref)\n\nfinds extref in links and returns the full URL that resolves the link.\n\nArguments\n\nlinks: the [InterLinks] instance to resolve the reference in\nextref: a string of the form \"@extref [inventory] [[:domain][:role]:]name\"\n\n\n\n\n\n","category":"method"},{"location":"howtos/#How-Tos","page":"How-Tos","title":"How-Tos","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Pages=[\"howtos.md\"]\nDepth=3:3","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"","category":"page"},{"location":"howtos/#howto-inventory-location","page":"How-Tos","title":"How do I find a project's inventory file?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"The documentation generator should generate an inventory file in the root of its output folder. These then get deployed with the rest of the documentation. For most projects, this \"root\" ends up in a subfolder named after the version or branch.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"For example, you will find objects.inv inventory files under the following URLs:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"https://www.sphinx-doc.org/en/master/objects.inv\nhttps://matplotlib.org/3.7.3/objects.inv\nhttps://docs.python.org/3/objects.inv\nhttps://juliadocs.org/DocInventories.jl/stable/objects.inv\nhttps://juliadocs.org/DocInventories.jl/v0.2/objects.inv","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"The Julia language and Documenter.jl currently do not provide an inventory file, but if they did, it would be immediately underneath","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"https://docs.julialang.org/en/v1/\nhttps://documenter.juliadocs.org/stable/","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If it is not obvious where an inventory file is located, simply try to load it in the REPL until you find a working URL:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"using DocInventories\nInventory(\"https://www.sphinx-doc.org/en/objects.inv\")\nInventory(\"https://www.sphinx-doc.org/en/master/objects.inv\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If you cannot find any inventory file, see What if I want to link to a project that does not provide an inventory file?","category":"page"},{"location":"howtos/#howto-find-extref","page":"How-Tos","title":"How do I figure out the correct name for the @extref link?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Use the search capabilities of InterLinks or DocInventories.Inventory.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If you have set up an InterLinks object named links in your docs/make.jl as described before, you are presumably able to build your documentation locally by starting a Julia REPL in the appropriate environment (e.g., julia --project=docs) and then running include(\"docs/make.jl\").","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"This also puts the links object into your REPL, allowing you to search it interactively.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"# include(\"docs/make.jl\")\nusing DocumenterInterLinks # hide\nlinks = InterLinks(\"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\", \"matplotlib\" => \"https://matplotlib.org/3.7.3/\", \"Documenter\" => (\"https://documenter.juliadocs.org/stable/\", joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")), \"Julia\" => (\"https://docs.julialang.org/en/v1/\", joinpath(@__DIR__, \"inventories\", \"Julia.toml\"))); # hide\nlinks","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"For example, trying to find the appropriate @extref link to to the LaTeX Syntax section in the Documenter manual, you might search for","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links[\"Documenter\"](\"latex\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"and determine that an appropriate @extref would be","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"[LaTeX Syntax](@extref Documenter :label:`latex_syntax`)","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"This search is quite flexible. Using regular expression, you could do something crazy like search the Julia documentation for docstrings of any method that involves two or more strings:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links[\"Julia\"](r\":method:`.*-.*AbstractString.*AbstractString.*`\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"You can also search across all projects, using a lookup in the InterLinks object directly, e.g.,","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links(\"`index`\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"These matching @extref links should be modified according to the Recommended Syntax.","category":"page"},{"location":"howtos/#howto-manual-inventory","page":"How-Tos","title":"What if I want to link to a project that does not provide an inventory file?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Inventory files really should created automatically using a documentation generator. Try to get the project to use one that produces inventory files or help them set up their documentation system so that it does.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Until Documenter incorporates the Inventory Generation currently provided by this plugin, one may produce an inventory file for an existing Julia/Documenter-based project by cloning the project, opening a REPL so that include(\"docs/make.jl\") successfully builds the documentation for that projects, and then repeat include(\"docs/make.jl\") after running","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"julia> ] add DocumenterInterLinks\njulia> using DocumenterInterLinks","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"in the same REPL. You should then find an objects.inv in the docs/build folder. Use the DocInventories package to convert it to TOML Format. This is how the inventory files used in this documentation were generated, e.g., for the Julia project itself.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"There may be projects that legitimately do not provide inventories. For example, some simple Julia projects write out their entire documentation in their README on Github. In that case, you should either use standard links or manually create an inventory file. The easiest way to do this is to write out an inventory in TOML Format by hand.","category":"page"},{"location":"howtos/#howto-external-links","page":"How-Tos","title":"Can I use this plugin for general external links?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Documenter's markdown flavor lacks the ability for reference links. If you link to the same very long URLs repeatedly, this becomes cumbersome.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"In principle, you could manually write out an inventory file that defines link labels and their associated URLs, along the lines of the discussion in Documenter's PR #1351. Whether you should abuse DocumenterInterLinks in this way might be a matter of debate.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"A situation where I do think this makes sense is if you repeatedly link to some website with very structured content, e.g. Wikipedia or the Julia Discourse Forum. As shown in the DocInventories documentation, you could write a Wikipedia inventory file just for the articles you want to link to, and then have a link such as","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"[Julia](@extref Wikipedia)","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"in your documentation to link to Julia (programming language).","category":"page"},{"location":"write_inventory/#Inventory-Generation","page":"Inventory Generation","title":"Inventory Generation","text":"","category":"section"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"The inventory files that get loaded into InterLinks are typically generated 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, Documenter.jl does the same with the help of this plugin: Just by loading DocumenterInterLinks in docs/make.jl, the WriteInventory pipeline step is added to the process of generating the documentation. This automatically results in a Sphinx-compatible objects.inv inventory file being written to docs/build/.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"warning: Warning\nThe creation of an objects.inv and/or some other inventory file should become part directly of the Documenter.jl package in the future. See Documenter issue #2366.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"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.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"For a Documenter-based project, the automatic inventory contains:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"An entry for every docstring included in the documentation. These use the ad-hoc jl domain and a role that depends on the object.\nAn entry for every section heading. To ensure compatibility with Sphinx, these entries use the std domain, the label role, a slugified version of the heading (or the explicit header @id) as a name, and the full heading (stripped of formatting, but including spaces) as the dispname.\nAn entry for every page in the documentation. These use the std domain and the doc 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.","category":"page"},{"location":"write_inventory/#The-Julia-Domain","page":"Inventory Generation","title":"The Julia Domain","text":"","category":"section"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"DocumenterInterLinks.WriteInventory writes 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:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"\"Macro\" (role macro): for macros. For example, \":jl:macro:`Base.@inbounds`\" for Base.@inbounds.\n\"Keyword\" (role keyword): for Julia keywords (used in the documentation of the Julia language itself, only). For example, \":jl:keyword:`if`\" for the if keyword.\n\"Function\" (role function): for functions. For example, \":jl:function:`Statistics.mean`\" for Statistics.mean.\n\"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.\n\"Type\" (role type): For types, both structs and abstract types. For example, \":jl:type:`Base.AbstractMatrix`\" for AbstractMatrix.\n\"Module\" (role module): For modules. For example, \":jl:module:`LinearAlgebra.BLAS`\" for LinearAlgebra.BLAS.\n\"Constant\" (role constant): For documented data / constants inside a module. For example, \":jl:constant:`Base.VERSION`\" for Julia's VERSION constant.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"As discussed in Syntax, the domain and roles are for disambiguation only. In practice, the above example references might be written as","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"* [`Base.@inbounds`](@extref)\n* [the `if` keyword](@extref Julia `if`)\n* [`Statistics.mean`](@extref)\n* [`*` operator of two matrices](@extref `Base.:*-Tuple{AbstractMatrix, AbstractMatrix}`)\n* [`LinearAlgebra.BLAS`](@extref)\n* [Julia's `VERSION` constant](@extref `Base.VERSION`)","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"These render as:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"Base.@inbounds\nthe if keyword\nStatistics.mean\n* operator of two matrices\nLinearAlgebra.BLAS\nJulia's VERSION constant","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"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.","category":"page"},{"location":"#DocumenterInterLinks.jl","page":"Home","title":"DocumenterInterLinks.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"using Markdown\nusing Pkg\n\nVERSION = Pkg.dependencies()[Base.UUID(\"d12716ef-a0f6-4df4-a9f1-a5a34e75c656\")].version\n\ngithub_badge = \"[![Github](https://img.shields.io/badge/JuliaDocs-DocumenterInterLinks.jl-blue.svg?logo=github)](https://github.com/JuliaDocs/DocumenterInterLinks.jl)\"\n\nversion_badge = \"![v$VERSION](https://img.shields.io/badge/version-v$(replace(\"$VERSION\", \"-\" => \"--\"))-green.svg)\"\n\nif get(ENV, \"DOCUMENTER_BUILD_PDF\", \"\") == \"\"\n Markdown.parse(\"$github_badge $version_badge\")\nelse\n Markdown.parse(\"\"\"\n -----\n\n On Github: [JuliaDocs/DocumenterInterLinks.jl](https://github.com/JuliaDocs/DocumenterInterLinks.jl)\n\n Version: $VERSION\n\n -----\n\n \"\"\")\nend","category":"page"},{"location":"","page":"Home","title":"Home","text":"DocumenterInterLinks.jl is a plugin for Documenter.jl to link to external projects. It is interoperable with Intersphinx.","category":"page"},{"location":"#Installation-Instructions","page":"Home","title":"Installation Instructions","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"As usual, the package can be installed via","category":"page"},{"location":"","page":"Home","title":"Home","text":"] add DocumenterInterLinks","category":"page"},{"location":"","page":"Home","title":"Home","text":"in the Julia REPL, or by adding","category":"page"},{"location":"","page":"Home","title":"Home","text":"DocumenterInterLinks = \"d12716ef-a0f6-4df4-a9f1-a5a34e75c656\"","category":"page"},{"location":"","page":"Home","title":"Home","text":"to the relevant Project.toml file.","category":"page"},{"location":"#Usage","page":"Home","title":"Usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In your docs/make.jl file, load the DocumenterInterLinks package (using DocumenterInterLinks).\nDeclare external projects by instantiating an InterLinks object and passing it as part of plugins to Documenter.makedocs.\nReference items from any external project with an @extref link in your documentation.","category":"page"},{"location":"#Declaring-External-Projects","page":"Home","title":"Declaring External Projects","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In docs/make.jl, instantiate an InterLinks object to define external projects you want to link to. For example,","category":"page"},{"location":"","page":"Home","title":"Home","text":"using DocumenterInterLinks\n\nlinks = InterLinks(\n \"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\",\n \"matplotlib\" => \"https://matplotlib.org/3.7.3/\",\n \"Documenter\" => (\n \"https://documenter.juliadocs.org/stable/\",\n joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")\n ),\n \"Julia\" => (\n \"https://docs.julialang.org/en/v1/\",\n joinpath(@__DIR__, \"inventories\", \"Julia.toml\")\n ),\n);\nnothing # hide","category":"page"},{"location":"","page":"Home","title":"Home","text":"defines the external projects \"sphinx\", \"matplotlib\", and \"Julia\". For each project, it specifies the root URL of that project's online documentation and the location of an inventory file.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The above examples illustrates three possibilities for specifying the root url and inventory location","category":"page"},{"location":"","page":"Home","title":"Home","text":"Map the project name to the URL of an inventory file. The project root URL is the given URL without the filename.\nMap that project name to project root URL. This will look for an inventory file objects.inv directly underneath the given URL.\nMap the project name to a tuple containing the root URL first, and then one or more possible locations for an inventory file. These may be local file paths, which allows using a self-maintained inventory file for a project that does not provide one.","category":"page"},{"location":"","page":"Home","title":"Home","text":"See the doc-string of InterLinks for details.","category":"page"},{"location":"","page":"Home","title":"Home","text":"warning: Warning\nThe instantiated links object must be passed to Documenter.makedocs as an element to the plugins keyword argument.","category":"page"},{"location":"#Inventories","page":"Home","title":"Inventories","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The inventory files referenced when instantiating InterLinks are assumed to have been created by a documentation generator, see Inventory Generation. The DocInventories package is used as a backend to parse these files into DocInventories.Inventory objects. These are accessible by using links as an ordered dict:","category":"page"},{"location":"","page":"Home","title":"Home","text":"links[\"sphinx\"]","category":"page"},{"location":"","page":"Home","title":"Home","text":"As we can see, inventories contain a mapping of names to linkable locations relative to the root URL of a project's online documentation, see DocInventories.InventoryItem.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The DocInventories package provides tools for interactively searching inventories for items to reference. See Exploring Inventories and How do I figure out the correct name for the @extref link?.","category":"page"},{"location":"#Using-External-References","page":"Home","title":"Using External References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The DocumenterInterLinks plugin adds support for @extref link targets to Documenter. At the most fundamental level, they work just like Documenter's standard @ref link targets. Replacing @ref with @extref switches from a local reference to an external one:","category":"page"},{"location":"","page":"Home","title":"Home","text":"* [`Documenter.makedocs`](@extref)\n* [Documenter's `makedocs` function](@extref `Documenter.makedocs`)\n* See the section about Documenter's [Writers](@extref).","category":"page"},{"location":"","page":"Home","title":"Home","text":"The above markdown code renders as follows:","category":"page"},{"location":"","page":"Home","title":"Home","text":"Documenter.makedocs\nDocumenter's makedocs function\nSee the section about Documenter's Writers.","category":"page"},{"location":"","page":"Home","title":"Home","text":"To disambiguate (and speed up) the references, the name of the inventory (as defined when instantiating InterLinks) can be included in the @extref. The previous example would have been better written as","category":"page"},{"location":"","page":"Home","title":"Home","text":"* See the section about Documenter's [Writers](@extref Documenter).","category":"page"},{"location":"","page":"Home","title":"Home","text":"to clarify that we are linking to the section name \"Writers\" found in links[\"Documenter\"]. When the link text and link target differ, the inventory name should be given between @extref and the target name, e.g., [`Regex`](@extref Julia Base.Regex), which turns into \"Regex\".","category":"page"},{"location":"","page":"Home","title":"Home","text":"Since DocumenterInterLinks is fully compatible with Sphinx inventories, it also provides an extended @extref syntax that builds on the Sphinx concept of \"domains\" and \"roles\". You will see these when inspecting an InventoryItem:","category":"page"},{"location":"","page":"Home","title":"Home","text":"using DocInventories\n\nDocInventories.show_full(links[\"Documenter\"][\"Documenter.makedocs\"])","category":"page"},{"location":"","page":"Home","title":"Home","text":"We can include the domain and role in an @extref link as","category":"page"},{"location":"","page":"Home","title":"Home","text":"* [`makedocs`](@extref :function:`Documenter.makedocs`)\n* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)","category":"page"},{"location":"","page":"Home","title":"Home","text":"using a syntax that is reminiscent of the Sphinx cross-referencing syntax. The use of domains and roles in DocumenterInterLinks (unlike in Sphinx) is for disambiguation only, in case there are multiple items with the same name. In general, follow the Recommended Syntax guidelines.","category":"page"},{"location":"sphinx/#Compatibility-with-Sphinx","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"","category":"section"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"info: Info\nThis section goes into some fairly technical details. You do not need to read it unless you use both Documenter and Sphinx and plan to link both ways between Julia and Python projects.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"DocumenterInterLinks is interoperable with Sphinx and Intersphinx: The InterLinks object can refer to the objects.inv file that Sphinx automatically writes out for every project. This makes it possible to easily link to virtually every Python project (as well as any other C/C++/Fortran project that uses Sphinx for its documentation).","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"The possible specification :domain:role:`name` in an @extref link mimics the cross-referencing syntax in Sphinx. However, Sphinx reStructuredText is much more explicit than Documenter's markdown syntax. In particular, the domain and role are required for every reference (although projects can set up a default domain, usually py, which can then be omitted). This is not the case in the @extref syntax defined by DocumenterInterLinks, where domain and role are for disambiguation only and can (and usually should) be omitted.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"Moreover, domains and roles must be formally defined in Sphinx. In fact, Sphinx makes a distinction between \"type\" and \"role\". Strictly speaking, the objects.inv file records an \"object type\", like function or module, which DocInventories.InventoryItem reads in as role. A Sphinx domain then defines \"roles\" on top of that which are used for referencing object. The formal definition of the domain includes a mapping between an object type and one or more roles. Consider for example the code of the PythonDomain, which defines an object type function with associated roles func and obj. In contrast, DocumenterInterLinks has no formally defined domains and makes no distinction between object types and roles. Thus, the inventory item links[\"matplotlib\"][\":py:function:`matplotlib.get_backend`\"] would be referenced as :py:func:`matplotlib.get_backend` (using :func:, not :function:!) or :py:obj:`matplotlib.get_backend` in Sphinx, but as [`get_backend`](@extref :py:function:`matplotlib.get_backend`) in DocumenterInterLinks, or more simply without any domain or role as [`matplotlib.get_backend`](@extref).","category":"page"},{"location":"sphinx/#Referencing-the-Julia-domain-in-Sphinx","page":"Compatibility with Sphinx","title":"Referencing the Julia domain in Sphinx","text":"","category":"section"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"The formal nature of Sphinx domains also has consequences for referencing Julia objects from within a Sphinx project. Linking from a project using Sphinx as a documentation generator to a Julia project using Documenter and the automatic inventory generation provided by DocumenterInterLinks will not work out of the box. This is because Sphinx does not know about the jl domain. In this sense, the jl domain is considered \"ad-hoc\".","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"There is a Sphinx-Julia package, but that package is currently not functional, and only partially supports the object types / roles used here in The Julia Domain.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"Thus, any Sphinx project that wants to link to inventory items in the jl domain must first formally specify that domain. This could be done by adding the following code to the Sphinx conf.py file (or an extension):","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"from sphinx.domains import Domain, ObjType\nfrom sphinx.roles import XRefRole\n\nclass JuliaDomain(Domain):\n \"\"\"A minimal Julia language domain.\"\"\"\n\n name = 'jl'\n label = 'Julia'\n object_types = {\n # name => (localized name, *roles)\n 'macro': ObjType('macro', 'macro', 'obj'),\n 'keyword': ObjType('keyword', 'keyword', 'obj'),\n 'function': ObjType('function', 'func', 'function', 'obj'),\n 'method': ObjType('method', 'meth', 'method', 'obj'),\n 'type': ObjType('type', 'type', 'obj'),\n 'module': ObjType('module', 'mod', 'module', 'obj'),\n 'constant': ObjType('constant', 'const', 'constant', 'obj'),\n }\n\n roles = {\n 'macro': XRefRole(fix_parens=True),\n 'keyword': XRefRole(),\n 'function': XRefRole(fix_parens=True),\n 'func': XRefRole(fix_parens=True),\n 'method': XRefRole(fix_parens=True),\n 'meth': XRefRole(fix_parens=True),\n 'type': XRefRole(fix_parens=True),\n 'module': XRefRole(),\n 'mod': XRefRole(),\n 'constant': XRefRole(),\n 'const': XRefRole(),\n 'obj': XRefRole(),\n }\n\n\ndef setup(app):\n app.add_domain(JuliaDomain)","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"We have used Sphinx' Domain API here to define the object types matching our Julia Domain. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx' usual conventions, such as :func: as a shorthand for :function: and obj for any type.","category":"page"},{"location":"syntax/#Syntax","page":"Syntax","title":"Syntax","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The possible forms of an @extref link are as follows:","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[title](@extref) where title is a section title\n[`name`](@extref) where name is a fully specified code object 🏅\n[text](@extref name) where text is an arbitrary link text\n[text](@extref `name`) where name is a fully specified code object or sluggified section title 🏅\n[title](@extref project) where project is a known project in the underlying InterLinks object 🥈\n[`name`](@extref project) 🥈\n[text](@extref :role:`name`)\n[text](@extref :domain:role:`name`)\n[text](@extref project name)\n[text](@extref project `name`) 🏅\n[text](@extref project :role:`name`) 🥈\n[text](@extref project :domain:role:`name`)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The most commonly used forms of syntax should be (2), (4), and (10) 🏅, with (5), (6), and (11) being useful in some situations 🥈, see the Recommended Syntax.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Assuming an InterLinks instance links, all of the above will reference the DocInventories.InventoryItem links[project][\":domain:role:name\"]. If project is not specified, the first project in links that contains a matching item will be used (up to a performance shortcut). If domain or role are not given, any domain or role will match.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Forms (1-3) most directly extend Documenter's built-in @ref syntax, but are not universally recommended for optimum performance. Form (5) takes precedence over form (3) if project is a known element of links. The use of backticks in form (4) would avoid this ambiguity.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Note that forms (1) and (5) apply a sluggification to transform title into a name. This matches Documenter's @ref behavior for linking to section titles. In contrast, forms (3) or (9) (just like [text](@ref name)) do not transform name and should receive an already sluggified title. In practice, linking to section titles directly tends to be tricky, and it is often better to search in the inventory for the actual name or header @id of the section one wants to link to, and then use form (10) to avoid all ambiguity.","category":"page"},{"location":"syntax/#Performance-Tips","page":"Syntax","title":"Performance Tips","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Although resolving external references is unlikely to have a significant impact on the build time of a project's documentation, there are some internals that affect the relative performance of the above @extref syntax forms.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When no project is given in the @extref specification, all projects declared in the InterLinks object may have to be searched for a matching item. The projects are searched in order, so the ordering in the definition of InterLinks matters.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"However, DocumenterInterLinks implements a short-circuit mechanism to avoid having to specify the project when linking to code objects in most cases: If name is enclosed in backticks, and starts with the name of a project followed by a period, then that project is searched first.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"For example, in order to link to Documenter.makedocs, we can use","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Documenter.makedocs`](@extref)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"to immediately search the inventory links[\"Documenter\"], making the reference lookup as efficient as for the more verbose","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Documenter.makedocs`](@extref Documenter)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Further @extref calls that will use the short-circuit mechanism for efficient lookup are","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`makedocs`](@extref `Documenter.makedocs`)\n[`makedocs`](@extref :function:`Documenter.makedocs`)\n[`makedocs`](@extref :jl:function:`Documenter.makedocs`)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"where the latter two are unnecessarily verbose, as Documenter.makedocs is already uniquely specified without the role or domain.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"On the other hand,","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`makedocs`](@extref Documenter.makedocs)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"will work, but it will not use the short-circuit mechanism, due to the lack of backticks.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The short-circuit mechanism only works if the project name used in the instantiation of InterLinks matches the package name as it occurs in the fully specified name of any code object. That is, name the project \"Documenter\", not, e.g., \"Documenter121\" for version 1.2.1 of Documenter.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When this is not possible, e.g. for the Julia project which contains many different modules without a common prefix (Base, Core, LinearAlgebra, …), it is best to declare that project as the first element in InterLinks. That way,","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Base.sort!`](@extref)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"looks in the Julia project first, avoiding the need for","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Base.sort!`](@extref Julia)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"(although you may still prefer the latter as a matter of clarity).","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"warning: Warning\nIf possible, use the name of a package as it occurs in the fully specified name of any code objects when declaring the project in InterLinks.","category":"page"},{"location":"syntax/#Recommended-Syntax","page":"Syntax","title":"Recommended Syntax","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"With the Performance Tips in mind, not all of the 12 possible Syntax forms are recommended in practice. For maximum clarity and performance, use the following guidelines:","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When referencing section headers in another project, e.g. the Basic Markdown section in Documenter's documentation, use form (5):\n[Basic Markdown](@extref Documenter)\nOr, look up the appropriate sluggified name:\nusing DocumenterInterLinks # hide\nlinks = InterLinks(\"Documenter\" => (\"https://documenter.juliadocs.org/stable/\", joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")),) # hide\nlinks[\"Documenter\"](\"Basic Markdown\")\nand use the more robust form (10):\n[Basic Markdown](@extref Documenter `Basic-Markdown`)\nIn any case, always specify the project name when referencing section titles.\nWhen directly referencing a code object, e.g., Documenter.makedocs, use form (2):\n[`Documenter.makedocs`](@extref)\nMake sure that Documenter is a project name in links (see Performance Tips).\nThis gets slightly more complicated when the code object is a \"method\" (where the docstring is for specific types of arguments), e.g., Documenter.parseblock. You will generally have to look up the full name\nlinks[\"Documenter\"](\"parseblock\")\nand then use form (4),\n[`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`)\nWhen referencing a page, e.g. the Home page of the Documenter documentation, use form (11):\n[Home page of the Documenter documentation](@extref Documenter :doc:`index`)\nThe doc role is not strictly necessary, but it clearly distinguishes references to documents from references to headings (especially when both may exist with the same name).","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Thus, the most commonly used forms of syntax for @extref links should be (2), (4), and (10), highlighted with 🏅 in Syntax.","category":"page"}] +[{"location":"api/internals/#Internals","page":"Internals","title":"Internals","text":"","category":"section"},{"location":"api/internals/","page":"Internals","title":"Internals","text":"Modules = [DocumenterInterLinks]","category":"page"},{"location":"api/internals/#DocumenterInterLinks.ExtCrossReferences","page":"Internals","title":"DocumenterInterLinks.ExtCrossReferences","text":"Pipeline step to expand all @extref cross-references.\n\nThis runs before Documenter.Builder.CrossReferences.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.InterLinks","page":"Internals","title":"DocumenterInterLinks.InterLinks","text":"Plugin for enabling external links in Documenter.jl.\n\nlinks = InterLinks(\n \"project1\" => \"https://project1.url/\",\n \"project2\" => \"https://project2.url/inventory.file\",\n \"project3\" => (\n \"https://project3.url/\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"inventory.file\")\n );\n default_inventory_file=\"objects.inv\"\n)\n\ninstantiates a plugin object that must be passed as an element of the plugins keyword argument to Documenter.makedocs. This then enables @extref links in the project's documentation to be resolved, see the Documentation for details.\n\nArguments\n\nThe InterLinks plugin receives mappings of project names to the project root URL and inventory locations. Each project names must be an alphanumerical ASCII string. For Julia projects, it should be the name of the package without the .jl suffix, e.g., \"Documenter\" for Documenter.jl. For Python projects, it should be the name of project's main module.\n\nThe root url / inventory location (the value of the mapping), can be given in any of the following forms:\n\nA single string with a URL of the inventory file, e.g.\n\"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\"`\nThe root URL relative which all URIs inside the inventory are taken to be relative is everything up to the final slash in the inventory URL, \"https://www.sphinx-doc.org/en/master/\" in this case.\nA single string with a project root URL, for example,\n\"sphinx\" => \"https://www.sphinx-doc.org/en/master/\",`\nwhich must end with slash. This looks for the inventory file with the name corresponding to default_inventory_file directly underneath the given root URL.\nA tuple of strings, where the first element is the project root URL and all subsequent elements are locations (URLs or local file paths) to an inventory file, e.g.,\n\"Julia\" => (\n \"https://docs.julialang.org/en/v1/\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"Julia.toml\")\n),\n\"Documenter\" => (\n \"https://documenter.juliadocs.org/stable/\",\n \"https://documenter.juliadocs.org/stable/inventory.toml.gz\",\n joinpath(@__DIR__, \"src\", \"interlinks\", \"Documenter.toml\")\n)\nThe first reachable inventory file will be used. This enables, e.g., to define a local inventory file as a fallback in case the online inventory file location is unreachable, as in the last example.\nA DocInventories.Inventory instance.\n\nProperties\n\nnames: A list of project names\ninventories: A dictionary of project names to DocInventories.Inventory instances\nrx: a Regex that matches any valid @extref expression that can be resolved.\n\nThe InterLinks object also acts as a (read-only) ordered dictionary so that, e.g., links[\"project1\"] returns the DocInventories.Inventory for that project.\n\nSearch\n\nFree-form search in a particular inventory is possible with, e.g.,\n\nlinks[\"Julia\"](search)\n\nSee the discussion on search in the DocInventories.Inventory documentation. Such a search returns a list of matching DocInventories.InventoryItem instances.\n\nIn addition,\n\nlinks(search)\n\nallows to search across all inventories. This returns a list of @extref strings that could be used to reference the matching items.\n\nMethods\n\nfind_in_interlinks(links, extref) – find the URL for an extref\n\nSee also\n\nThe InterLinks mapping is deliberately reminiscent of the intersphinx_mapping setting in Sphinx.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.WriteInventory","page":"Internals","title":"DocumenterInterLinks.WriteInventory","text":"Pipeline step to write the objects.inv inventory to the build directory.\n\nThis runs after Documenter.Builder.RenderDocument and only if Documenter was set up for HTML output.\n\n\n\n\n\n","category":"type"},{"location":"api/internals/#DocumenterInterLinks.find_in_interlinks-Tuple{InterLinks, AbstractString}","page":"Internals","title":"DocumenterInterLinks.find_in_interlinks","text":"Find an @extref link in any of the InterLinks inventories.\n\nurl = find_in_interlinks(links, extref)\n\nfinds extref in links and returns the full URL that resolves the link.\n\nArguments\n\nlinks: the [InterLinks] instance to resolve the reference in\nextref: a string of the form \"@extref [project] [[:domain][:role]:]name\"\n\n\n\n\n\n","category":"method"},{"location":"howtos/#How-Tos","page":"How-Tos","title":"How-Tos","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Pages=[\"howtos.md\"]\nDepth=3:3","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"","category":"page"},{"location":"howtos/#howto-inventory-location","page":"How-Tos","title":"How do I find a project's inventory file?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"The documentation generator should generate an inventory file in the root of its output folder. These then get deployed with the rest of the documentation. For most projects, this \"root\" ends up in a subfolder named after the version or branch.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"For example, you will find objects.inv inventory files under the following URLs:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"https://www.sphinx-doc.org/en/master/objects.inv\nhttps://matplotlib.org/3.7.3/objects.inv\nhttps://docs.python.org/3/objects.inv\nhttps://juliadocs.org/DocInventories.jl/stable/objects.inv\nhttps://juliadocs.org/DocInventories.jl/v0.2/objects.inv","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"The Julia language and Documenter.jl currently do not provide an inventory file, but if they did, it would be immediately underneath","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"https://docs.julialang.org/en/v1/\nhttps://documenter.juliadocs.org/stable/","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If it is not obvious where an inventory file is located, simply try to load it in the REPL until you find a working URL:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"using DocInventories\nInventory(\"https://www.sphinx-doc.org/en/objects.inv\")\nInventory(\"https://www.sphinx-doc.org/en/master/objects.inv\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If you cannot find any inventory file, see What if I want to link to a project that does not provide an inventory file?","category":"page"},{"location":"howtos/#howto-find-extref","page":"How-Tos","title":"How do I figure out the correct name for the @extref link?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Use the search capabilities of InterLinks or DocInventories.Inventory.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"If you have set up an InterLinks object named links in your docs/make.jl as described before, you are presumably able to build your documentation locally by starting a Julia REPL in the appropriate environment (e.g., julia --project=docs) and then running include(\"docs/make.jl\").","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"This also puts the links object into your REPL, allowing you to search it interactively.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"# include(\"docs/make.jl\")\nusing DocumenterInterLinks # hide\nlinks = InterLinks(\"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\", \"matplotlib\" => \"https://matplotlib.org/3.7.3/\", \"Documenter\" => (\"https://documenter.juliadocs.org/stable/\", joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")), \"Julia\" => (\"https://docs.julialang.org/en/v1/\", joinpath(@__DIR__, \"inventories\", \"Julia.toml\"))); # hide\nlinks","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"For example, trying to find the appropriate @extref link to to the LaTeX Syntax section in the Documenter manual, you might search for","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links[\"Documenter\"](\"latex\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"and determine that an appropriate @extref would be","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"[LaTeX Syntax](@extref Documenter :label:`latex_syntax`)","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"This search is quite flexible. Using regular expression, you could do something crazy like search the Julia documentation for docstrings of any method that involves two or more strings:","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links[\"Julia\"](r\":method:`.*-.*AbstractString.*AbstractString.*`\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"You can also search across all projects, using a lookup in the InterLinks object directly, e.g.,","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"links(\"`index`\")","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"These matching @extref links should be modified according to the Recommended Syntax.","category":"page"},{"location":"howtos/#howto-manual-inventory","page":"How-Tos","title":"What if I want to link to a project that does not provide an inventory file?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Inventory files really should created automatically using a documentation generator. Try to get the project to use one that produces inventory files or help them set up their documentation system so that it does.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Until Documenter incorporates the Inventory Generation currently provided by this plugin, one may produce an inventory file for an existing Julia/Documenter-based project by cloning the project, opening a REPL so that include(\"docs/make.jl\") successfully builds the documentation for that projects, and then repeat include(\"docs/make.jl\") after running","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"julia> ] add DocumenterInterLinks\njulia> using DocumenterInterLinks","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"in the same REPL. You should then find an objects.inv in the docs/build folder. Use the DocInventories package to convert it to TOML Format. This is how the inventory files used in this documentation were generated, e.g., for the Julia project itself.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"There may be projects that legitimately do not provide inventories. For example, some simple Julia projects write out their entire documentation in their README on Github. In that case, you should either use standard links or manually create an inventory file. The easiest way to do this is to write out an inventory in TOML Format by hand.","category":"page"},{"location":"howtos/#howto-external-links","page":"How-Tos","title":"Can I use this plugin for general external links?","text":"","category":"section"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"Documenter's markdown flavor lacks the ability for reference links. If you link to the same very long URLs repeatedly, this becomes cumbersome.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"In principle, you could manually write out an inventory file that defines link labels and their associated URLs, along the lines of the discussion in Documenter's PR #1351. Whether you should abuse DocumenterInterLinks in this way might be a matter of debate.","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"A situation where I do think this makes sense is if you repeatedly link to some website with very structured content, e.g. Wikipedia or the Julia Discourse Forum. As shown in the DocInventories documentation, you could write a Wikipedia inventory file just for the articles you want to link to, and then have a link such as","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"[Julia](@extref Wikipedia)","category":"page"},{"location":"howtos/","page":"How-Tos","title":"How-Tos","text":"in your documentation to link to Julia (programming language).","category":"page"},{"location":"write_inventory/#Inventory-Generation","page":"Inventory Generation","title":"Inventory Generation","text":"","category":"section"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"The inventory files that get loaded into InterLinks are typically generated 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, Documenter.jl does the same with the help of this plugin: Just by loading DocumenterInterLinks in docs/make.jl, the WriteInventory pipeline step is added to the process of generating the documentation. This automatically results in a Sphinx-compatible objects.inv inventory file being written to docs/build/.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"warning: Warning\nThe creation of an objects.inv and/or some other inventory file should become part directly of the Documenter.jl package in the future. See Documenter issue #2366.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"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.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"For a Documenter-based project, the automatic inventory contains:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"An entry for every docstring included in the documentation. These use the ad-hoc jl domain and a role that depends on the object.\nAn entry for every section heading. To ensure compatibility with Sphinx, these entries use the std domain, the label role, a slugified version of the heading (or the explicit header @id) as a name, and the full heading (stripped of formatting, but including spaces) as the dispname.\nAn entry for every page in the documentation. These use the std domain and the doc 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.","category":"page"},{"location":"write_inventory/#The-Julia-Domain","page":"Inventory Generation","title":"The Julia Domain","text":"","category":"section"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"DocumenterInterLinks.WriteInventory writes 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:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"\"Macro\" (role macro): for macros. For example, \":jl:macro:`Base.@inbounds`\" for Base.@inbounds.\n\"Keyword\" (role keyword): for Julia keywords (used in the documentation of the Julia language itself, only). For example, \":jl:keyword:`if`\" for the if keyword.\n\"Function\" (role function): for functions. For example, \":jl:function:`Statistics.mean`\" for Statistics.mean.\n\"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.\n\"Type\" (role type): For types, both structs and abstract types. For example, \":jl:type:`Base.AbstractMatrix`\" for AbstractMatrix.\n\"Module\" (role module): For modules. For example, \":jl:module:`LinearAlgebra.BLAS`\" for LinearAlgebra.BLAS.\n\"Constant\" (role constant): For documented data / constants inside a module. For example, \":jl:constant:`Base.VERSION`\" for Julia's VERSION constant.","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"As discussed in Syntax, the domain and roles are for disambiguation only. In practice, the above example references might be written as","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"* [`Base.@inbounds`](@extref)\n* [the `if` keyword](@extref Julia `if`)\n* [`Statistics.mean`](@extref)\n* [`*` operator of two matrices](@extref `Base.:*-Tuple{AbstractMatrix, AbstractMatrix}`)\n* [`LinearAlgebra.BLAS`](@extref)\n* [Julia's `VERSION` constant](@extref `Base.VERSION`)","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"These render as:","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"Base.@inbounds\nthe if keyword\nStatistics.mean\n* operator of two matrices\nLinearAlgebra.BLAS\nJulia's VERSION constant","category":"page"},{"location":"write_inventory/","page":"Inventory Generation","title":"Inventory Generation","text":"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.","category":"page"},{"location":"#DocumenterInterLinks.jl","page":"Home","title":"DocumenterInterLinks.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"using Markdown\nusing Pkg\n\nVERSION = Pkg.dependencies()[Base.UUID(\"d12716ef-a0f6-4df4-a9f1-a5a34e75c656\")].version\n\ngithub_badge = \"[![Github](https://img.shields.io/badge/JuliaDocs-DocumenterInterLinks.jl-blue.svg?logo=github)](https://github.com/JuliaDocs/DocumenterInterLinks.jl)\"\n\nversion_badge = \"![v$VERSION](https://img.shields.io/badge/version-v$(replace(\"$VERSION\", \"-\" => \"--\"))-green.svg)\"\n\nif get(ENV, \"DOCUMENTER_BUILD_PDF\", \"\") == \"\"\n Markdown.parse(\"$github_badge $version_badge\")\nelse\n Markdown.parse(\"\"\"\n -----\n\n On Github: [JuliaDocs/DocumenterInterLinks.jl](https://github.com/JuliaDocs/DocumenterInterLinks.jl)\n\n Version: $VERSION\n\n -----\n\n \"\"\")\nend","category":"page"},{"location":"","page":"Home","title":"Home","text":"DocumenterInterLinks.jl is a plugin for Documenter.jl to link to external projects. It is interoperable with Intersphinx.","category":"page"},{"location":"#Installation-Instructions","page":"Home","title":"Installation Instructions","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"As usual, the package can be installed via","category":"page"},{"location":"","page":"Home","title":"Home","text":"] add DocumenterInterLinks","category":"page"},{"location":"","page":"Home","title":"Home","text":"in the Julia REPL, or by adding","category":"page"},{"location":"","page":"Home","title":"Home","text":"DocumenterInterLinks = \"d12716ef-a0f6-4df4-a9f1-a5a34e75c656\"","category":"page"},{"location":"","page":"Home","title":"Home","text":"to the relevant Project.toml file.","category":"page"},{"location":"#Usage","page":"Home","title":"Usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In your docs/make.jl file, load the DocumenterInterLinks package (using DocumenterInterLinks).\nDeclare external projects by instantiating an InterLinks object and passing it as part of plugins to Documenter.makedocs.\nReference items from any external project with an @extref link in your documentation.","category":"page"},{"location":"#Declaring-External-Projects","page":"Home","title":"Declaring External Projects","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In docs/make.jl, instantiate an InterLinks object to define external projects you want to link to. For example,","category":"page"},{"location":"","page":"Home","title":"Home","text":"using DocumenterInterLinks\n\nlinks = InterLinks(\n \"sphinx\" => \"https://www.sphinx-doc.org/en/master/objects.inv\",\n \"matplotlib\" => \"https://matplotlib.org/3.7.3/\",\n \"Documenter\" => (\n \"https://documenter.juliadocs.org/stable/\",\n joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")\n ),\n \"Julia\" => (\n \"https://docs.julialang.org/en/v1/\",\n joinpath(@__DIR__, \"inventories\", \"Julia.toml\")\n ),\n);\nnothing # hide","category":"page"},{"location":"","page":"Home","title":"Home","text":"defines the external projects \"sphinx\", \"matplotlib\", and \"Julia\". For each project, it specifies the root URL of that project's online documentation and the location of an inventory file.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The above examples illustrates three possibilities for specifying the root url and inventory location","category":"page"},{"location":"","page":"Home","title":"Home","text":"Map the project name to the URL of an inventory file. The project root URL is the given URL without the filename.\nMap that project name to project root URL. This will look for an inventory file objects.inv directly underneath the given URL.\nMap the project name to a tuple containing the root URL first, and then one or more possible locations for an inventory file. These may be local file paths, which allows using a self-maintained inventory file for a project that does not provide one.","category":"page"},{"location":"","page":"Home","title":"Home","text":"See the doc-string of InterLinks for details.","category":"page"},{"location":"","page":"Home","title":"Home","text":"warning: Warning\nThe instantiated links object must be passed to Documenter.makedocs as an element to the plugins keyword argument.","category":"page"},{"location":"#Inventories","page":"Home","title":"Inventories","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The inventory files referenced when instantiating InterLinks are assumed to have been created by a documentation generator, see Inventory Generation. The DocInventories package is used as a backend to parse these files into DocInventories.Inventory objects. These are accessible by using links as an ordered dict:","category":"page"},{"location":"","page":"Home","title":"Home","text":"links[\"sphinx\"]","category":"page"},{"location":"","page":"Home","title":"Home","text":"As we can see, inventories contain a mapping of names to linkable locations relative to the root URL of a project's online documentation, see DocInventories.InventoryItem.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The DocInventories package provides tools for interactively searching inventories for items to reference. See Exploring Inventories and How do I figure out the correct name for the @extref link?.","category":"page"},{"location":"#Using-External-References","page":"Home","title":"Using External References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The DocumenterInterLinks plugin adds support for @extref link targets to Documenter. At the most fundamental level, they work just like Documenter's standard @ref link targets. Replacing @ref with @extref switches from a local reference to an external one:","category":"page"},{"location":"","page":"Home","title":"Home","text":"* [`Documenter.makedocs`](@extref)\n* [Documenter's `makedocs` function](@extref `Documenter.makedocs`)\n* See the section about Documenter's [Writers](@extref).","category":"page"},{"location":"","page":"Home","title":"Home","text":"The above markdown code renders as follows:","category":"page"},{"location":"","page":"Home","title":"Home","text":"Documenter.makedocs\nDocumenter's makedocs function\nSee the section about Documenter's Writers.","category":"page"},{"location":"","page":"Home","title":"Home","text":"To disambiguate (and speed up) the references, the name of the inventory (as defined when instantiating InterLinks) can be included in the @extref. The previous example would have been better written as","category":"page"},{"location":"","page":"Home","title":"Home","text":"* See the section about Documenter's [Writers](@extref Documenter).","category":"page"},{"location":"","page":"Home","title":"Home","text":"to clarify that we are linking to the section name \"Writers\" found in links[\"Documenter\"]. When the link text and link target differ, the inventory name should be given between @extref and the target name, e.g., [`Regex`](@extref Julia Base.Regex), which turns into \"Regex\".","category":"page"},{"location":"","page":"Home","title":"Home","text":"Since DocumenterInterLinks is fully compatible with Sphinx inventories, it also provides an extended @extref syntax that builds on the Sphinx concept of \"domains\" and \"roles\". You will see these when inspecting an InventoryItem:","category":"page"},{"location":"","page":"Home","title":"Home","text":"using DocInventories\n\nDocInventories.show_full(links[\"Documenter\"][\"Documenter.makedocs\"])","category":"page"},{"location":"","page":"Home","title":"Home","text":"We can include the domain and role in an @extref link as","category":"page"},{"location":"","page":"Home","title":"Home","text":"* [`makedocs`](@extref :function:`Documenter.makedocs`)\n* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)","category":"page"},{"location":"","page":"Home","title":"Home","text":"using a syntax that is reminiscent of the Sphinx cross-referencing syntax. The use of domains and roles in DocumenterInterLinks (unlike in Sphinx) is for disambiguation only, in case there are multiple items with the same name. In general, follow the Recommended Syntax guidelines.","category":"page"},{"location":"sphinx/#Compatibility-with-Sphinx","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"","category":"section"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"info: Info\nThis section goes into some fairly technical details. You do not need to read it unless you use both Documenter and Sphinx and plan to link both ways between Julia and Python projects.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"DocumenterInterLinks is interoperable with Sphinx and Intersphinx: The InterLinks object can refer to the objects.inv file that Sphinx automatically writes out for every project. This makes it possible to easily link to virtually every Python project (as well as any other C/C++/Fortran project that uses Sphinx for its documentation).","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"The possible specification :domain:role:`name` in an @extref link mimics the cross-referencing syntax in Sphinx. However, Sphinx reStructuredText is much more explicit than Documenter's markdown syntax. In particular, the domain and role are required for every reference (although projects can set up a default domain, usually py, which can then be omitted). This is not the case in the @extref syntax defined by DocumenterInterLinks, where domain and role are for disambiguation only and can (and usually should) be omitted.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"Moreover, domains and roles must be formally defined in Sphinx. In fact, Sphinx makes a distinction between \"type\" and \"role\". Strictly speaking, the objects.inv file records an \"object type\", like function or module, which DocInventories.InventoryItem reads in as role. A Sphinx domain then defines \"roles\" on top of that which are used for referencing object. The formal definition of the domain includes a mapping between an object type and one or more roles. Consider for example the code of the PythonDomain, which defines an object type function with associated roles func and obj. In contrast, DocumenterInterLinks has no formally defined domains and makes no distinction between object types and roles. Thus, the inventory item links[\"matplotlib\"][\":py:function:`matplotlib.get_backend`\"] would be referenced as :py:func:`matplotlib.get_backend` (using :func:, not :function:!) or :py:obj:`matplotlib.get_backend` in Sphinx, but as [`get_backend`](@extref :py:function:`matplotlib.get_backend`) in DocumenterInterLinks, or more simply without any domain or role as [`matplotlib.get_backend`](@extref).","category":"page"},{"location":"sphinx/#Referencing-the-Julia-domain-in-Sphinx","page":"Compatibility with Sphinx","title":"Referencing the Julia domain in Sphinx","text":"","category":"section"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"The formal nature of Sphinx domains also has consequences for referencing Julia objects from within a Sphinx project. Linking from a project using Sphinx as a documentation generator to a Julia project using Documenter and the automatic inventory generation provided by DocumenterInterLinks will not work out of the box. This is because Sphinx does not know about the jl domain. In this sense, the jl domain is considered \"ad-hoc\".","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"There is a Sphinx-Julia package, but that package is currently not functional, and only partially supports the object types / roles used here in The Julia Domain.","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"Thus, any Sphinx project that wants to link to inventory items in the jl domain must first formally specify that domain. This could be done by adding the following code to the Sphinx conf.py file (or an extension):","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"from sphinx.domains import Domain, ObjType\nfrom sphinx.roles import XRefRole\n\nclass JuliaDomain(Domain):\n \"\"\"A minimal Julia language domain.\"\"\"\n\n name = 'jl'\n label = 'Julia'\n object_types = {\n # name => (localized name, *roles)\n 'macro': ObjType('macro', 'macro', 'obj'),\n 'keyword': ObjType('keyword', 'keyword', 'obj'),\n 'function': ObjType('function', 'func', 'function', 'obj'),\n 'method': ObjType('method', 'meth', 'method', 'obj'),\n 'type': ObjType('type', 'type', 'obj'),\n 'module': ObjType('module', 'mod', 'module', 'obj'),\n 'constant': ObjType('constant', 'const', 'constant', 'obj'),\n }\n\n roles = {\n 'macro': XRefRole(fix_parens=True),\n 'keyword': XRefRole(),\n 'function': XRefRole(fix_parens=True),\n 'func': XRefRole(fix_parens=True),\n 'method': XRefRole(fix_parens=True),\n 'meth': XRefRole(fix_parens=True),\n 'type': XRefRole(fix_parens=True),\n 'module': XRefRole(),\n 'mod': XRefRole(),\n 'constant': XRefRole(),\n 'const': XRefRole(),\n 'obj': XRefRole(),\n }\n\n\ndef setup(app):\n app.add_domain(JuliaDomain)","category":"page"},{"location":"sphinx/","page":"Compatibility with Sphinx","title":"Compatibility with Sphinx","text":"We have used Sphinx' Domain API here to define the object types matching our Julia Domain. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx' usual conventions, such as :func: as a shorthand for :function: and obj for any type.","category":"page"},{"location":"syntax/#Syntax","page":"Syntax","title":"Syntax","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The possible forms of an @extref link are as follows:","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[title](@extref) where title is a section title\n[`name`](@extref) where name is a fully specified code object 🏅\n[text](@extref name) where text is an arbitrary link text\n[text](@extref `name`) where name is a fully specified code object or sluggified section title 🏅\n[title](@extref project) where project is a known project in the underlying InterLinks object 🥈\n[`name`](@extref project) 🥈\n[text](@extref :role:`name`)\n[text](@extref :domain:role:`name`)\n[text](@extref project name)\n[text](@extref project `name`) 🏅\n[text](@extref project :role:`name`) 🥈\n[text](@extref project :domain:role:`name`)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The most commonly used forms of syntax should be (2), (4), and (10) 🏅, with (5), (6), and (11) being useful in some situations 🥈, see the Recommended Syntax.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Assuming an InterLinks instance links, all of the above will reference the DocInventories.InventoryItem links[project][\":domain:role:name\"]. If project is not specified, the first project in links that contains a matching item will be used (up to a performance shortcut). If domain or role are not given, any domain or role will match.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Forms (1-3) most directly extend Documenter's built-in @ref syntax, but are not universally recommended for optimum performance. Form (5) takes precedence over form (3) if project is a known element of links. The use of backticks in form (4) would avoid this ambiguity.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Note that forms (1) and (5) apply a sluggification to transform title into a name. This matches Documenter's @ref behavior for linking to section titles. In contrast, forms (3) or (9) (just like [text](@ref name)) do not transform name and should receive an already sluggified title. In practice, linking to section titles directly tends to be tricky, and it is often better to search in the inventory for the actual name or header @id of the section one wants to link to, and then use form (10) to avoid all ambiguity.","category":"page"},{"location":"syntax/#Performance-Tips","page":"Syntax","title":"Performance Tips","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Although resolving external references is unlikely to have a significant impact on the build time of a project's documentation, there are some internals that affect the relative performance of the above @extref syntax forms.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When no project is given in the @extref specification, all projects declared in the InterLinks object may have to be searched for a matching item. The projects are searched in order, so the ordering in the definition of InterLinks matters.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"However, DocumenterInterLinks implements a short-circuit mechanism to avoid having to specify the project when linking to code objects in most cases: If name is enclosed in backticks, and starts with the name of a project followed by a period, then that project is searched first.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"For example, in order to link to Documenter.makedocs, we can use","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Documenter.makedocs`](@extref)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"to immediately search the inventory links[\"Documenter\"], making the reference lookup as efficient as for the more verbose","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Documenter.makedocs`](@extref Documenter)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Further @extref calls that will use the short-circuit mechanism for efficient lookup are","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`makedocs`](@extref `Documenter.makedocs`)\n[`makedocs`](@extref :function:`Documenter.makedocs`)\n[`makedocs`](@extref :jl:function:`Documenter.makedocs`)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"where the latter two are unnecessarily verbose, as Documenter.makedocs is already uniquely specified without the role or domain.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"On the other hand,","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`makedocs`](@extref Documenter.makedocs)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"will work, but it will not use the short-circuit mechanism, due to the lack of backticks.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"The short-circuit mechanism only works if the project name used in the instantiation of InterLinks matches the package name as it occurs in the fully specified name of any code object. That is, name the project \"Documenter\", not, e.g., \"Documenter121\" for version 1.2.1 of Documenter.","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When this is not possible, e.g. for the Julia project which contains many different modules without a common prefix (Base, Core, LinearAlgebra, …), it is best to declare that project as the first element in InterLinks. That way,","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Base.sort!`](@extref)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"looks in the Julia project first, avoiding the need for","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"[`Base.sort!`](@extref Julia)","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"(although you may still prefer the latter as a matter of clarity).","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"warning: Warning\nIf possible, use the name of a package as it occurs in the fully specified name of any code objects when declaring the project in InterLinks.","category":"page"},{"location":"syntax/#Recommended-Syntax","page":"Syntax","title":"Recommended Syntax","text":"","category":"section"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"With the Performance Tips in mind, not all of the 12 possible Syntax forms are recommended in practice. For maximum clarity and performance, use the following guidelines:","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"When referencing section headers in another project, e.g. the Basic Markdown section in Documenter's documentation, use form (5):\n[Basic Markdown](@extref Documenter)\nOr, look up the appropriate sluggified name:\nusing DocumenterInterLinks # hide\nlinks = InterLinks(\"Documenter\" => (\"https://documenter.juliadocs.org/stable/\", joinpath(@__DIR__, \"inventories\", \"Documenter.toml\")),) # hide\nlinks[\"Documenter\"](\"Basic Markdown\")\nand use the more robust form (10):\n[Basic Markdown](@extref Documenter `Basic-Markdown`)\nIn any case, always specify the project name when referencing section titles.\nWhen directly referencing a code object, e.g., Documenter.makedocs, use form (2):\n[`Documenter.makedocs`](@extref)\nMake sure that Documenter is a project name in links (see Performance Tips).\nThis gets slightly more complicated when the code object is a \"method\" (where the docstring is for specific types of arguments), e.g., Documenter.parseblock. You will generally have to look up the full name\nlinks[\"Documenter\"](\"parseblock\")\nand then use form (4),\n[`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`)\nWhen referencing a page, e.g. the Home page of the Documenter documentation, use form (11):\n[Home page of the Documenter documentation](@extref Documenter :doc:`index`)\nThe doc role is not strictly necessary, but it clearly distinguishes references to documents from references to headings (especially when both may exist with the same name).","category":"page"},{"location":"syntax/","page":"Syntax","title":"Syntax","text":"Thus, the most commonly used forms of syntax for @extref links should be (2), (4), and (10), highlighted with 🏅 in Syntax.","category":"page"}] } diff --git a/dev/sphinx/index.html b/dev/sphinx/index.html index 78f6331..8ba821f 100644 --- a/dev/sphinx/index.html +++ b/dev/sphinx/index.html @@ -35,4 +35,4 @@ def setup(app): - app.add_domain(JuliaDomain)

    We have used Sphinx' Domain API here to define the object types matching our Julia Domain. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx' usual conventions, such as :func: as a shorthand for :function: and obj for any type.

    + app.add_domain(JuliaDomain)

    We have used Sphinx' Domain API here to define the object types matching our Julia Domain. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx' usual conventions, such as :func: as a shorthand for :function: and obj for any type.

    diff --git a/dev/syntax/index.html b/dev/syntax/index.html index a2c45b2..fc8cf5c 100644 --- a/dev/syntax/index.html +++ b/dev/syntax/index.html @@ -3,4 +3,4 @@ [`makedocs`](@extref :function:`Documenter.makedocs`) [`makedocs`](@extref :jl:function:`Documenter.makedocs`)

    where the latter two are unnecessarily verbose, as Documenter.makedocs is already uniquely specified without the role or domain.

    On the other hand,

    [`makedocs`](@extref Documenter.makedocs)

    will work, but it will not use the short-circuit mechanism, due to the lack of backticks.

    The short-circuit mechanism only works if the project name used in the instantiation of InterLinks matches the package name as it occurs in the fully specified name of any code object. That is, name the project "Documenter", not, e.g., "Documenter121" for version 1.2.1 of Documenter.

    When this is not possible, e.g. for the Julia project which contains many different modules without a common prefix (Base, Core, LinearAlgebra, …), it is best to declare that project as the first element in InterLinks. That way,

    [`Base.sort!`](@extref)

    looks in the Julia project first, avoiding the need for

    [`Base.sort!`](@extref Julia)

    (although you may still prefer the latter as a matter of clarity).

    Warning

    If possible, use the name of a package as it occurs in the fully specified name of any code objects when declaring the project in InterLinks.

    With the Performance Tips in mind, not all of the 12 possible Syntax forms are recommended in practice. For maximum clarity and performance, use the following guidelines:

    1. When referencing section headers in another project, e.g. the Basic Markdown section in Documenter's documentation, use form (5):

      [Basic Markdown](@extref Documenter)

      Or, look up the appropriate sluggified name:

      links["Documenter"]("Basic Markdown")
      1-element Vector{DocInventories.InventoryItem}:
  InventoryItem(":std:label:`Basic-Markdown`" => "showcase/#\$", dispname="Basic Markdown")

      and use the more robust form (10):

      [Basic Markdown](@extref Documenter `Basic-Markdown`)

      In any case, always specify the project name when referencing section titles.

    2. When directly referencing a code object, e.g., Documenter.makedocs, use form (2):

      [`Documenter.makedocs`](@extref)

      Make sure that Documenter is a project name in links (see Performance Tips).

      This gets slightly more complicated when the code object is a "method" (where the docstring is for specific types of arguments), e.g., Documenter.parseblock. You will generally have to look up the full name

      links["Documenter"]("parseblock")
      1-element Vector{DocInventories.InventoryItem}:
- InventoryItem(":jl:method:`Documenter.parseblock-Tuple{AbstractString, Any, Any}`" => "lib/internals/utilities/#Documenter.parseblock-Tuple%7BAbstractString%2C%20Any%2C%20Any%7D")

      and then use form (4),

      [`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`)

    3. When referencing a page, e.g. the Home page of the Documenter documentation, use form (11):

      [Home page of the Documenter documentation](@extref Documenter :doc:`index`)

      The doc role is not strictly necessary, but it clearly distinguishes references to documents from references to headings (especially when both may exist with the same name).

    Thus, the most commonly used forms of syntax for @extref links should be (2), (4), and (10), highlighted with 🏅 in Syntax.

    + InventoryItem(":jl:method:`Documenter.parseblock-Tuple{AbstractString, Any, Any}`" => "lib/internals/utilities/#Documenter.parseblock-Tuple%7BAbstractString%2C%20Any%2C%20Any%7D")

    and then use form (4),

    [`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`)

  • When referencing a page, e.g. the Home page of the Documenter documentation, use form (11):

    [Home page of the Documenter documentation](@extref Documenter :doc:`index`)

    The doc role is not strictly necessary, but it clearly distinguishes references to documents from references to headings (especially when both may exist with the same name).

    • Thus, the most commonly used forms of syntax for @extref links should be (2), (4), and (10), highlighted with 🏅 in Syntax.

    diff --git a/dev/write_inventory/index.html b/dev/write_inventory/index.html index c77646e..cbc72c7 100644 --- a/dev/write_inventory/index.html +++ b/dev/write_inventory/index.html @@ -4,4 +4,4 @@ * [`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.

    +* [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.