hc
2023-12-08 01573e231f18eb2d99162747186f59511f56b64d
kernel/Documentation/doc-guide/sphinx.rst
....@@ -1,3 +1,5 @@
1
+.. _sphinxdoc:
2
+
13 Introduction
24 ============
35
....@@ -25,8 +27,7 @@
2527 ==============
2628
2729 The ReST markups currently used by the Documentation/ files are meant to be
28
-built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
29
-PDF outputs, it is recommended to use version 1.4.6 or upper.
30
+built with ``Sphinx`` version 1.3 or higher.
3031
3132 There's a script that checks for the Sphinx requirements. Please see
3233 :ref:`sphinx-pre-install` for further details.
....@@ -35,15 +36,15 @@
3536 and it is not uncommon that upgrading it or some other Python packages
3637 on your machine would cause the documentation build to break.
3738
38
-A way to get rid of that is to use a different version than the one shipped
39
-on your distributions. In order to do that, it is recommended to install
39
+A way to avoid that is to use a different version than the one shipped
40
+with your distributions. In order to do so, it is recommended to install
4041 Sphinx inside a virtual environment, using ``virtualenv-3``
4142 or ``virtualenv``, depending on how your distribution packaged Python 3.
4243
4344 .. note::
4445
4546 #) Sphinx versions below 1.5 don't work properly with Python's
46
- docutils version 0.13.1 or upper. So, if you're willing to use
47
+ docutils version 0.13.1 or higher. So, if you're willing to use
4748 those versions, you should run ``pip install 'docutils==0.12'``.
4849
4950 #) It is recommended to use the RTD theme for html output. Depending
....@@ -54,13 +55,13 @@
5455 those expressions are written using LaTeX notation. It needs texlive
5556 installed with amdfonts and amsmath in order to evaluate them.
5657
57
-In summary, if you want to install Sphinx version 1.4.9, you should do::
58
+In summary, if you want to install Sphinx version 1.7.9, you should do::
5859
59
- $ virtualenv sphinx_1.4
60
- $ . sphinx_1.4/bin/activate
61
- (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
60
+ $ virtualenv sphinx_1.7.9
61
+ $ . sphinx_1.7.9/bin/activate
62
+ (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
6263
63
-After running ``. sphinx_1.4/bin/activate``, the prompt will change,
64
+After running ``. sphinx_1.7.9/bin/activate``, the prompt will change,
6465 in order to indicate that you're using the new environment. If you
6566 open a new shell, you need to rerun this command to enter again at
6667 the virtual environment before building the documentation.
....@@ -80,7 +81,7 @@
8081 PDF and LaTeX builds
8182 --------------------
8283
83
-Such builds are currently supported only with Sphinx versions 1.4 and upper.
84
+Such builds are currently supported only with Sphinx versions 1.4 and higher.
8485
8586 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
8687
....@@ -103,8 +104,8 @@
103104 You should run:
104105
105106 sudo dnf install -y texlive-luatex85
106
- /usr/bin/virtualenv sphinx_1.4
107
- . sphinx_1.4/bin/activate
107
+ /usr/bin/virtualenv sphinx_1.7.9
108
+ . sphinx_1.7.9/bin/activate
108109 pip install -r Documentation/sphinx/requirements.txt
109110
110111 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
....@@ -216,7 +217,7 @@
216217 examples, etc.), use ``::`` for anything that doesn't really benefit
217218 from syntax highlighting, especially short snippets. Use
218219 ``.. code-block:: <language>`` for longer code blocks that benefit
219
- from highlighting.
220
+ from highlighting. For a short snippet of code embedded in the text, use \`\`.
220221
221222
222223 the C domain
....@@ -240,11 +241,14 @@
240241
241242 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
242243 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
243
-changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
244
+changed to ``VIDIOC_LOG_STATUS``.
244245
245
-.. code-block:: rst
246
-
247
- :c:func:`VIDIOC_LOG_STATUS`
246
+Please note that there is no need to use ``c:func:`` to generate cross
247
+references to function documentation. Due to some Sphinx extension magic,
248
+the documentation build system will automatically turn a reference to
249
+``function()`` into a cross reference if an index entry for the given
250
+function name exists. If you see ``c:func:`` use in a kernel document,
251
+please feel free to remove it.
248252
249253
250254 list tables
....@@ -333,6 +337,23 @@
333337
334338 - column 3
335339
340
+Cross-referencing
341
+-----------------
342
+
343
+Cross-referencing from one documentation page to another can be done by passing
344
+the path to the file starting from the Documentation folder.
345
+For example, to cross-reference to this page (the .rst extension is optional)::
346
+
347
+ See Documentation/doc-guide/sphinx.rst.
348
+
349
+If you want to use a relative path, you need to use Sphinx's ``doc`` directive.
350
+For example, referencing this page from the same directory would be done as::
351
+
352
+ See :doc:`sphinx`.
353
+
354
+For information on cross-referencing to kernel-doc functions or types, see
355
+Documentation/doc-guide/kernel-doc.rst.
356
+
336357 .. _sphinx_kfigure:
337358
338359 Figures & Images