change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/doc-guide/sphinx.rst
..
..
@@ -1,3 +1,5 @@
1
+.. _sphinxdoc:
2
+
1
3
 Introduction
2
4
 ============
3
5
 
..
..
@@ -25,8 +27,7 @@
25
27
 ==============
26
28
 
27
29
 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.
30
31
 
31
32
 There's a script that checks for the Sphinx requirements. Please see
32
33
 :ref:`sphinx-pre-install` for further details.
..
..
@@ -35,15 +36,15 @@
35
36
 and it is not uncommon that upgrading it or some other Python packages
36
37
 on your machine would cause the documentation build to break.
37
38
 
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
40
41
 Sphinx inside a virtual environment, using ``virtualenv-3``
41
42
 or ``virtualenv``, depending on how your distribution packaged Python 3.
42
43
 
43
44
 .. note::
44
45
 
45
46
    #) 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
47
48
       those versions, you should run ``pip install 'docutils==0.12'``.
48
49
 
49
50
    #) It is recommended to use the RTD theme for html output. Depending
..
..
@@ -54,13 +55,13 @@
54
55
       those expressions are written using LaTeX notation. It needs texlive
55
56
       installed with amdfonts and amsmath in order to evaluate them.
56
57
 
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::
58
59
 
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
62
63
 
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,
64
65
 in order to indicate that you're using the new environment. If you
65
66
 open a new shell, you need to rerun this command to enter again at
66
67
 the virtual environment before building the documentation.
..
..
@@ -80,7 +81,7 @@
80
81
 PDF and LaTeX builds
81
82
 --------------------
82
83
 
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.
84
85
 
85
86
 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
86
87
 
..
..
@@ -103,8 +104,8 @@
103
104
 	You should run:
104
105
 
105
106
 		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
108
109
 		pip install -r Documentation/sphinx/requirements.txt
109
110
 
110
111
 	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
..
..
@@ -216,7 +217,7 @@
216
217
   examples, etc.), use ``::`` for anything that doesn't really benefit
217
218
   from syntax highlighting, especially short snippets. Use
218
219
   ``.. 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 \`\`.
220
221
 
221
222
 
222
223
 the C domain
..
..
@@ -240,11 +241,14 @@
240
241
 
241
242
 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
242
243
 ``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``.
244
245
 
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.
248
252
 
249
253
 
250
254
 list tables
..
..
@@ -333,6 +337,23 @@
333
337
 
334
338
         - column 3
335
339
 
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
+
336
357
 .. _sphinx_kfigure:
337
358
 
338
359
 Figures & Images