-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Documenter.jl
committed
Jan 4, 2024
1 parent
b24e7f9
commit 80deb50
Showing
9 changed files
with
133 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| {"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-03T06:03:19","documenter_version":"1.2.1"}} | ||
| {"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-04T21:32:48","documenter_version":"1.2.1"}} |
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
Binary file not shown.
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| <!DOCTYPE html> | ||
| <html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Compatibility with Sphinx · DocumenterInterLinks.jl</title><meta name="title" content="Compatibility with Sphinx · DocumenterInterLinks.jl"/><meta property="og:title" content="Compatibility with Sphinx · DocumenterInterLinks.jl"/><meta property="twitter:title" content="Compatibility with Sphinx · DocumenterInterLinks.jl"/><meta name="description" content="Documentation for DocumenterInterLinks.jl."/><meta property="og:description" content="Documentation for DocumenterInterLinks.jl."/><meta property="twitter:description" content="Documentation for DocumenterInterLinks.jl."/><meta property="og:url" content="https://juliadocs.org/DocumenterInterLinks.jl/sphinx/"/><meta property="twitter:url" content="https://juliadocs.org/DocumenterInterLinks.jl/sphinx/"/><link rel="canonical" href="https://juliadocs.org/DocumenterInterLinks.jl/sphinx/"/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">DocumenterInterLinks.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li><a class="tocitem" href="../syntax/">Syntax</a></li><li><a class="tocitem" href="../write_inventory/">Inventory Generation</a></li><li class="is-active"><a class="tocitem" href>Compatibility with Sphinx</a></li><li><a class="tocitem" href="../howtos/">How-Tos</a></li><li><a class="tocitem" href="../api/internals/">Internals</a></li></ul><div class="docs-version-selector field has-addons visible"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"><option value="#" selected="selected">0.2.0+dev</option></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Compatibility with Sphinx</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Compatibility with Sphinx</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/JuliaDocs/DocumenterInterLinks.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/JuliaDocs/DocumenterInterLinks.jl/blob/master/docs/src/sphinx.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Compatibility-with-Sphinx"><a class="docs-heading-anchor" href="#Compatibility-with-Sphinx">Compatibility with Sphinx</a><a id="Compatibility-with-Sphinx-1"></a><a class="docs-heading-anchor-permalink" href="#Compatibility-with-Sphinx" title="Permalink"></a></h1><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>This 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.</p></div></div><p><code>DocumenterInterLinks</code> is interoperable with <a href="https://www.sphinx-doc.org/en/master/index.html">Sphinx</a> and <a href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html">Intersphinx</a>: The <a href="../api/internals/#DocumenterInterLinks.InterLinks"><code>InterLinks</code></a> object can refer to the <a href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html"><code>objects.inv</code></a> 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).</p><p>The possible specification <code>:domain:role:`name`</code> in an <code>@extref</code> link mimics <a href="https://www.sphinx-doc.org/en/master/usage/referencing.html#xref-syntax">the cross-referencing syntax in Sphinx</a>. However, Sphinx <a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">reStructuredText</a> is much more explicit than Documenter's <a href="https://documenter.juliadocs.org/stable/man/syntax/">markdown syntax</a>. In particular, the domain and role are <em>required</em> for every reference (although projects can set up a default domain, usually <code>py</code>, which can then be omitted). This is not the case in the <code>@extref</code> syntax defined by <code>DocumenterInterLinks</code>, where domain and role are for disambiguation only and can (and usually should) be omitted.</p><p>Moreover, <a href="https://www.sphinx-doc.org/en/master/extdev/domainapi.html#module-sphinx.domains">domains and roles</a> must be <em>formally defined</em> in Sphinx. In fact, Sphinx makes a distinction between "type" and "role". Strictly speaking, the <code>objects.inv</code> file records an "object type", like <code>function</code> or <code>module</code>, which <a href="https://juliadocs.org/DocInventories.jl/stable/api/#DocInventories.InventoryItem"><code>DocInventories.InventoryItem</code></a> reads in as <code>role</code>. A Sphinx domain then defines "roles" on top of that which are used for <em>referencing</em> 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 <a href="https://www.sphinx-doc.org/en/master/_modules/sphinx/domains/python.html#PythonDomain"><code>PythonDomain</code></a>, which defines an object type <code>function</code> with associated roles <code>func</code> and <code>obj</code>. In contrast, <code>DocumenterInterLinks</code> has no formally defined domains and makes no distinction between object types and roles. Thus, the inventory item <code>links["matplotlib"][":py:function:`matplotlib.get_backend`"]</code> would be referenced as <code>:py:func:`matplotlib.get_backend`</code> (using <code>:func:</code>, not <code>:function:</code>!) or <code>:py:obj:`matplotlib.get_backend`</code> in Sphinx, but as <code>[`get_backend`](@extref :py:function:`matplotlib.get_backend`)</code> in <code>DocumenterInterLinks</code>, or more simply without any domain or role as <code>[`matplotlib.get_backend`](@extref)</code>.</p><h3 id="Referencing-the-Julia-domain-in-Sphinx"><a class="docs-heading-anchor" href="#Referencing-the-Julia-domain-in-Sphinx">Referencing the Julia domain in Sphinx</a><a id="Referencing-the-Julia-domain-in-Sphinx-1"></a><a class="docs-heading-anchor-permalink" href="#Referencing-the-Julia-domain-in-Sphinx" title="Permalink"></a></h3><p>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 <a href="../write_inventory/#Inventory-Generation">inventory generation</a> provided by <code>DocumenterInterLinks</code> will not work out of the box. This is because Sphinx does not know about the <code>jl</code> domain. In this sense, the <code>jl</code> domain is considered "ad-hoc".</p><p>There is a <a href="https://github.com/bastikr/sphinx-julia">Sphinx-Julia</a> package, but that package is currently not functional, and only partially supports the object types / roles used here in <a href="../write_inventory/#The-Julia-Domain">The Julia Domain</a>.</p><p>Thus, any Sphinx project that wants to link to inventory items in the <code>jl</code> domain must first formally specify that domain. This could be done by adding the following code to the Sphinx <a href="https://www.sphinx-doc.org/en/master/usage/quickstart.html"><code>conf.py</code> file</a> (or an <a href="https://www.sphinx-doc.org/en/master/development/index.html">extension</a>):</p><pre><code class="language-python hljs">from sphinx.domains import Domain, ObjType | ||
| from sphinx.roles import XRefRole | ||
|
|
||
| class JuliaDomain(Domain): | ||
| """A minimal Julia language domain.""" | ||
|
|
||
| name = 'jl' | ||
| label = 'Julia' | ||
| object_types = { | ||
| # name => (localized name, *roles) | ||
| 'macro': ObjType('macro', 'macro', 'obj'), | ||
| 'keyword': ObjType('keyword', 'keyword', 'obj'), | ||
| 'function': ObjType('function', 'func', 'function', 'obj'), | ||
| 'method': ObjType('method', 'meth', 'method', 'obj'), | ||
| 'type': ObjType('type', 'type', 'obj'), | ||
| 'module': ObjType('module', 'mod', 'module', 'obj'), | ||
| 'constant': ObjType('constant', 'const', 'constant', 'obj'), | ||
| } | ||
|
|
||
| roles = { | ||
| 'macro': XRefRole(fix_parens=True), | ||
| 'keyword': XRefRole(), | ||
| 'function': XRefRole(fix_parens=True), | ||
| 'func': XRefRole(fix_parens=True), | ||
| 'method': XRefRole(fix_parens=True), | ||
| 'meth': XRefRole(fix_parens=True), | ||
| 'type': XRefRole(fix_parens=True), | ||
| 'module': XRefRole(), | ||
| 'mod': XRefRole(), | ||
| 'constant': XRefRole(), | ||
| 'const': XRefRole(), | ||
| 'obj': XRefRole(), | ||
| } | ||
|
|
||
|
|
||
| def setup(app): | ||
| app.add_domain(JuliaDomain)</code></pre><p>We have used Sphinx' <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' 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:32">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html> |
Oops, something went wrong.