sphinx.ext.intersphinx link to other projects documentation ! (the killer feature !) ¶
Example : reference in tuto_docker ¶
In this example, docker:tuto_docker is an outside reference:
Remark:
We use a :ref:`Python3.6 docker image <docker:tuto_docker>`.
1 extensions = [
2 'sphinx.ext.intersphinx',
3 'sphinx.ext.todo',
4 ]
5
6 intersphinx_mapping = {
7 'python': ('https://docs.python.org/', None),
8 'docker': ('https://gdevops.frama.io/opsindev/docker/', None),
9 }
Example for this documentation: ¶
1# Configuration file for the Sphinx documentation builder.
2#
3# This file only contains a selection of the most common options. For a full
4# list see the documentation:
5# http://www.sphinx-doc.org/en/master/config
6# -- Path setup --------------------------------------------------------------
7# If extensions (or modules to document with autodoc) are in another directory,
8# add these directories to sys.path here. If the directory is relative to the
9# documentation root, use os.path.abspath to make it absolute, like shown here.
10#
11# import os
12# import sys
13# sys.path.insert(0, os.path.abspath('.'))
14import platform
15from datetime import datetime
16from zoneinfo import ZoneInfo
17
18import sphinx
19import sphinx_material
20
21# If extensions (or modules to document with autodoc) are in another directory,
22# add these directories to sys.path here. If the directory is relative to the
23# documentation root, use os.path.abspath to make it absolute, like shown here.
24# sys.path.insert(0, os.path.abspath("./src"))
25
26
27project = "Tuto sphinx"
28html_title = project
29
30author = f"DevOps people"
31html_logo = "images/documentation.png"
32html_favicon = "images/documentation.png"
33release = "0.1.0"
34now = datetime.now(tz=ZoneInfo("Europe/Paris"))
35version = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H ({now.tzinfo})"
36today = version
37
38extensions = [
39 "sphinx.ext.autodoc",
40 "sphinx.ext.doctest",
41 "sphinx.ext.extlinks",
42 "sphinx.ext.intersphinx",
43 "sphinx.ext.todo",
44 "sphinx.ext.mathjax",
45 "sphinx.ext.viewcode",
46 "sphinx_copybutton",
47]
48
49# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
50extensions.append("sphinx_design")
51
52# Add any paths that contain templates here, relative to this directory.
53templates_path = ["_templates"]
54exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
55html_static_path = ["_static"]
56html_show_sourcelink = True
57html_sidebars = {
58 "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
59}
60extensions.append("sphinx_material")
61html_theme_path = sphinx_material.html_theme_path()
62html_context = sphinx_material.get_html_context()
63html_theme = "sphinx_material"
64
65extensions.append("sphinx.ext.intersphinx")
66intersphinx_mapping = {
67 "sphinx": ("https://www.sphinx-doc.org/en/master", None),
68 "sphinx_mat": ("https://gdevops.frama.io/documentation/sphinx-demos",
69 None,
70 ),
71 "python": ("https://docs.python.org/", None),
72 "tuto_python": ("https://gdevops.frama.io/python/tuto/", None),
73 "tuto_css": ("https://gdevops.frama.io/web/tuto-css/", None),
74 "tuto_django": ("https://gdevops.frama.io/django/tuto/", None),
75 "blockdiag": ("http://blockdiag.com/en/", None),
76 "tuto_doc": ("https://gdevops.frama.io/documentation/tuto/", None),
77 "doc_news": ("https://gdevops.frama.io/documentation/news", None),
78 "doc_formats": ("https://gdevops.frama.io/documentation/formats", None),
79}
80extensions.append("sphinx.ext.todo")
81todo_include_todos = True
82
83
84# material theme options (see theme.conf for more information)
85# https://gitlab.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf
86# Colors
87# The theme color for mobile browsers. Hex color.
88# theme_color = #3f51b5
89# Primary colors:
90# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
91# teal, green, light-green, lime, yellow, amber, orange, deep-orange,
92# brown, grey, blue-grey, white
93# Accent colors:
94# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
95# teal, green, light-green, lime, yellow, amber, orange, deep-orange
96# color_accent = blue
97# color_primary = blue-grey
98
99# material theme options (see theme.conf for more information)
100html_theme_options = {
101 "base_url": "https://gdevops.frama.io/documentation/sphinx",
102 "repo_url": "https://framagit.org/gdevops/documentation/sphinx",
103 "repo_name": project,
104 "html_minify": False,
105 "html_prettify": True,
106 "css_minify": True,
107 "globaltoc_depth": -1,
108 "repo_type": "gitlab",
109 "color_primary": "green",
110 "color_accent": "cyan",
111 "theme_color": "#2196f3",
112 "nav_title": f"{project} ({today})",
113 "master_doc": False,
114 "nav_links": [
115 {
116 "href": "genindex",
117 "internal": True,
118 "title": "Index",
119 },
120 {
121 "href": "https://gdevops.frama.io/documentation/linkertree",
122 "internal": False,
123 "title": "Liens documentation",
124 },
125 {
126 "href": "https://sphinx-themes.org/#themes/",
127 "internal": False,
128 "title": "Sphinx themes",
129 },
130 {
131 "href": "https://gdevops.frama.io/web/linkertree/",
132 "internal": False,
133 "title": "Liens Web",
134 },
135 {
136 "href": "https://linkertree.frama.io/pvergain/",
137 "internal": False,
138 "title": "Liens pvergain",
139 },
140 ],
141 "heroes": {
142 "index": "Tuto sphinx",
143 },
144 "table_classes": ["plain"],
145}
146# https://github.com/sphinx-contrib/yasfb
147extensions.append("yasfb")
148feed_base_url = html_theme_options["base_url"]
149feed_author = "Scribe"
150# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
151extensions.append("sphinx_design")
152# https://sphinx-tags.readthedocs.io/en/latest/quickstart.html#installation
153extensions.append("sphinx_tags")
154tags_create_tags = True
155# Whether to display tags using sphinx-design badges.
156tags_create_badges = True
157
158extlinks = {
159 "duref": (
160 "http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s",
161 "rST %s",
162 ),
163 "durole": (
164 "http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s",
165 "rST role %s",
166 ),
167 "dudir": (
168 "http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s",
169 "rST directive %s",
170 ),
171 "graphvizattr": (
172 "https://graphviz.org/docs/attrs/%s/",
173 "%s attribute",
174 ),
175 "dutree": (
176 "https://docutils.sourceforge.io/docs/ref/doctree.html#%s",
177 "%s",
178 ),
179}
180
181
182def setup(app):
183 from sphinx.ext.autodoc import cut_lines
184 from sphinx.util.docfields import GroupedField
185
186 app.add_object_type(
187 "confval",
188 "confval",
189 objname="configuration value",
190 indextemplate="pair: %s; configuration value",
191 )
192
193
194language = "fr"
195html_last_updated_fmt = ""
196
197todo_include_todos = True
198# html_favicon = "images/favicon.ico"
199
200html_use_index = True
201html_domain_indices = True
202
203
204rst_prolog = """
205.. |sphinx| image:: /images/documentation.png
206.. |eb| image:: /images/executable_book_avatar.png
207.. |yed| image:: /images/yed_avatar.png
208.. |vrt| image:: /images/vrt_avatar.png
209.. |arsouilles| image:: /images/arsouilles_avatar.png
210.. |FluxWeb| image:: /images/rss_avatar.webp
211"""
212copyright = f"2018-{now.year}, {author} Built with sphinx {sphinx.__version__} Python {platform.python_version()}"
Include HTML in generated Sphinx docs ¶
Takayuki Shimizukawa shimizukawa@gmail.com
répondre à: sphinx-dev@googlegroups.com
à: sphinx-dev@googlegroups.com
date: 30 octobre 2012 05:22
objet: Re: [sphinx-dev] Include HTML in generated Sphinx docs
intersphinx will meet your needs.
intersphinx support to link another “Sphinx Document” by using inventory like “objects.inv”.
But if you generate inventory by hand (or some program), you can use this mechanism. I wrote a sample: https://gist.github.com/3978232
intersphinx reference is here: http://sphinx-doc.org/ext/intersphinx.html
Best regards,
Takayuki SHIMIZUKAWA
Sphinx-users.jp
conf.py ¶
extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
'javaapi': ('http://api.example.com/', 'javaapi.inv'),
}
generate_javaapi_inv.py ¶
inventory_header = u'''\
# Sphinx inventory version 2
# Project: javaapi
# Version: 2.0
# The remainder of this file is compressed with zlib.
'''.encode('utf-8')
inventory_payload = u'''\
api1 std:label -1 api.html#api1 API 1
'''.encode('utf-8')
# inventory_payload lines spec:
# name domainname:type priority uri dispname
#
# * `name` -- fully qualified name
# * `dispname` -- name to display when searching/linking
# * `type` -- object type, a key in ``self.object_types``
# * `docname` -- the document where it is to be found
# * `anchor` -- the anchor name for the object
# * `priority` -- how "important" the object is (determines placement in search results)
#
# - 1: default priority (placed before full-text matches)
# - 0: object is important (placed before default-priority objects)
# - 2: object is unimportant (placed after full-text matches)
# - -1: object should not show up in search at all
#
inventory = inventory_header + zlib.compress(inventory_payload)
open('javaapi.inv','wb').write(inventory)
index.html ¶
<div class="section" id="example-link-to-outer-non-sphinx-by-using-intersphinx">
<h1>Example: Link to outer non-sphinx by using intersphinx<a class="headerlink" href="#example-link-to-outer-non-sphinx-by-using-intersphinx" title="Permalink to this headline">ツカ</a></h1>
<p><a class="reference external" href="http://api.example.com/api.html#api1" title="(in javaapi v2.0)"><em class="xref std std-ref">Java API 1</em></a></p>
</div>
index.txt ¶
Example: Link to outer non-sphinx by using intersphinx
==========================================================================
:ref:`Java API 1 <javaapi:api1>`