build based on 33ac2ad

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-04T21:43:53","documenter_version":"1.2.1"}}
+{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-04T21:46:37","documenter_version":"1.2.1"}}

dev/howtos/index.html

@@ -49,4 +49,4 @@
  "@extref matplotlib :std:doc:`index`"
  "@extref Documenter :std:doc:`index`"
  &quot;@extref Julia :std:doc:`index`&quot;</code></pre><p>These matching <code>@extref</code> links should be modified according to the <a href="../syntax/#Recommended-Syntax">Recommended Syntax</a>.</p><h3 id="howto-manual-inventory"><a class="docs-heading-anchor" href="#howto-manual-inventory">What if I want to link to a project that does not provide an inventory file?</a><a id="howto-manual-inventory-1"></a><a class="docs-heading-anchor-permalink" href="#howto-manual-inventory" title="Permalink"></a></h3><p>Inventory files really should created <a href="../write_inventory/#Inventory-Generation">automatically using a documentation generator</a>. Try to get the project to use one that produces inventory files or help them set up their documentation system so that it does.</p><p>Until <code>Documenter</code> incorporates the <a href="../write_inventory/#Inventory-Generation">Inventory Generation</a> 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 <code>include(&quot;docs/make.jl&quot;)</code> successfully builds the documentation for that projects, and then repeat <code>include(&quot;docs/make.jl&quot;)</code> after running</p><pre><code class="language-julia hljs">julia&gt; ] add DocumenterInterLinks
-julia&gt; using DocumenterInterLinks</code></pre><p>in the same REPL. You should then find an <code>objects.inv</code> in the <code>docs/build</code> folder. <a href="https://juliadocs.org/DocInventories.jl/stable/usage/#Saving-Inventories-to-File">Use the <code>DocInventories</code> package to convert it</a> to <a href="https://juliadocs.org/DocInventories.jl/stable/formats/#TOML-Format">TOML Format</a>. This is how the <a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl/tree/master/docs/src/inventories">inventory files</a> used in this documentation were generated, e.g., for the Julia project itself.</p><p>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 <a href="https://docs.julialang.org/en/v1/stdlib/Markdown/#Links">standard links</a> or <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Creating-Inventory-Files">manually create an inventory file</a>. The easiest way to do this is to write out an inventory in <a href="https://juliadocs.org/DocInventories.jl/stable/formats/#TOML-Format">TOML Format</a> by hand.</p><h3 id="howto-external-links"><a class="docs-heading-anchor" href="#howto-external-links">Can I use this plugin for general external links?</a><a id="howto-external-links-1"></a><a class="docs-heading-anchor-permalink" href="#howto-external-links" title="Permalink"></a></h3><p>Documenter&#39;s markdown flavor <a href="https://discourse.julialang.org/t/how-to-use-markdown-reference-links-with-documenter-jl/84232">lacks the ability for reference links</a>. If you link to the same very long URLs repeatedly, this becomes cumbersome.</p><p>In principle, you could <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Creating-Inventory-Files">manually write out an inventory file</a> that defines link labels and their associated URLs, along the lines of the discussion in <a href="https://github.com/JuliaDocs/Documenter.jl/pull/1351">Documenter&#39;s PR #1351</a>. Whether you <em>should</em> abuse <code>DocumenterInterLinks</code> in this way might be a matter of debate.</p><p>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 <a href="https://discourse.julialang.org">Julia Discourse Forum</a>. As <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Maintain-an-Inventory-TOML-File-by-Hand">shown in the <code>DocInventories</code> documentation</a>, you could write a <code>Wikipedia</code> inventory file just for the articles you want to link to, and then have a link such as</p><pre><code class="nohighlight hljs">[Julia](@extref Wikipedia)</code></pre><p>in your documentation to link to <a href="https://en.wikipedia.org/wiki/Julia_(programming_language)">Julia (programming language)</a>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../sphinx/">« Compatibility with Sphinx</a><a class="docs-footer-nextpage" href="../api/internals/">Internals »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:43">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+julia&gt; using DocumenterInterLinks</code></pre><p>in the same REPL. You should then find an <code>objects.inv</code> in the <code>docs/build</code> folder. <a href="https://juliadocs.org/DocInventories.jl/stable/usage/#Saving-Inventories-to-File">Use the <code>DocInventories</code> package to convert it</a> to <a href="https://juliadocs.org/DocInventories.jl/stable/formats/#TOML-Format">TOML Format</a>. This is how the <a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl/tree/master/docs/src/inventories">inventory files</a> used in this documentation were generated, e.g., for the Julia project itself.</p><p>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 <a href="https://docs.julialang.org/en/v1/stdlib/Markdown/#Links">standard links</a> or <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Creating-Inventory-Files">manually create an inventory file</a>. The easiest way to do this is to write out an inventory in <a href="https://juliadocs.org/DocInventories.jl/stable/formats/#TOML-Format">TOML Format</a> by hand.</p><h3 id="howto-external-links"><a class="docs-heading-anchor" href="#howto-external-links">Can I use this plugin for general external links?</a><a id="howto-external-links-1"></a><a class="docs-heading-anchor-permalink" href="#howto-external-links" title="Permalink"></a></h3><p>Documenter&#39;s markdown flavor <a href="https://discourse.julialang.org/t/how-to-use-markdown-reference-links-with-documenter-jl/84232">lacks the ability for reference links</a>. If you link to the same very long URLs repeatedly, this becomes cumbersome.</p><p>In principle, you could <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Creating-Inventory-Files">manually write out an inventory file</a> that defines link labels and their associated URLs, along the lines of the discussion in <a href="https://github.com/JuliaDocs/Documenter.jl/pull/1351">Documenter&#39;s PR #1351</a>. Whether you <em>should</em> abuse <code>DocumenterInterLinks</code> in this way might be a matter of debate.</p><p>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 <a href="https://discourse.julialang.org">Julia Discourse Forum</a>. As <a href="https://juliadocs.org/DocInventories.jl/stable/creating/#Maintain-an-Inventory-TOML-File-by-Hand">shown in the <code>DocInventories</code> documentation</a>, you could write a <code>Wikipedia</code> inventory file just for the articles you want to link to, and then have a link such as</p><pre><code class="nohighlight hljs">[Julia](@extref Wikipedia)</code></pre><p>in your documentation to link to <a href="https://en.wikipedia.org/wiki/Julia_(programming_language)">Julia (programming language)</a>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../sphinx/">« Compatibility with Sphinx</a><a class="docs-footer-nextpage" href="../api/internals/">Internals »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:46">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/index.html

@@ -43,4 +43,4 @@
   uri="lib/public/#Documenter.makedocs",
   dispname="Documenter.makedocs"
 )</code></pre><p>We can include the domain and role in an <code>@extref</code> link as</p><pre><code class="nohighlight hljs">* [`makedocs`](@extref :function:`Documenter.makedocs`)
-* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)</code></pre><p>using a <a href="syntax/#Syntax">syntax</a> that is reminiscent of the <a href="https://www.sphinx-doc.org/en/master/usage/referencing.html#xref-syntax">Sphinx cross-referencing syntax</a>. The use of domains and roles in <code>DocumenterInterLinks</code> (<a href="sphinx/#Compatibility-with-Sphinx">unlike in Sphinx</a>) is for disambiguation only, in case there are multiple items with the same <code>name</code>. In general, follow the <a href="syntax/#Recommended-Syntax">Recommended Syntax</a> guidelines.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="syntax/">Syntax »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:43">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)</code></pre><p>using a <a href="syntax/#Syntax">syntax</a> that is reminiscent of the <a href="https://www.sphinx-doc.org/en/master/usage/referencing.html#xref-syntax">Sphinx cross-referencing syntax</a>. The use of domains and roles in <code>DocumenterInterLinks</code> (<a href="sphinx/#Compatibility-with-Sphinx">unlike in Sphinx</a>) is for disambiguation only, in case there are multiple items with the same <code>name</code>. In general, follow the <a href="syntax/#Recommended-Syntax">Recommended Syntax</a> guidelines.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="syntax/">Syntax »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:46">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/sphinx/index.html

@@ -35,4 +35,4 @@
 
 
 def setup(app):
-    app.add_domain(JuliaDomain)</code></pre><p>We have used Sphinx&#39; <a href="https://www.sphinx-doc.org/en/master/extdev/domainapi.html#domain-api">Domain API</a> here to define the object types matching our <a href="../write_inventory/#The-Julia-Domain">Julia Domain</a>. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx&#39; usual conventions, such as <code>:func:</code> as a shorthand for <code>:function:</code> and <code>obj</code> for any type.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../write_inventory/">« Inventory Generation</a><a class="docs-footer-nextpage" href="../howtos/">How-Tos »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:43">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+    app.add_domain(JuliaDomain)</code></pre><p>We have used Sphinx&#39; <a href="https://www.sphinx-doc.org/en/master/extdev/domainapi.html#domain-api">Domain API</a> here to define the object types matching our <a href="../write_inventory/#The-Julia-Domain">Julia Domain</a>. For each object type, we define a role of the same name, as well as abbreviated roles in line with Sphinx&#39; usual conventions, such as <code>:func:</code> as a shorthand for <code>:function:</code> and <code>obj</code> for any type.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../write_inventory/">« Inventory Generation</a><a class="docs-footer-nextpage" href="../howtos/">How-Tos »</a><div class="flexbox-break"></div><p class="footer-message"><a href="https://github.com/JuliaDocs/DocumenterInterLinks.jl">DocumenterInterLinks.jl</a> v0.2.0+dev docs powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Thursday 4 January 2024 21:46">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>