From 151fecfb72a0d602dfe79790602ef64b4e241574 Mon Sep 17 00:00:00 2001
From: hc <hc@nodka.com>
Date: Mon, 19 Feb 2024 01:51:07 +0000
Subject: [PATCH] export RK_PA3
---
kernel/Documentation/doc-guide/sphinx.rst | 57 +++++++++++++++++++++++++++++++++++++++------------------
1 files changed, 39 insertions(+), 18 deletions(-)
diff --git a/kernel/Documentation/doc-guide/sphinx.rst b/kernel/Documentation/doc-guide/sphinx.rst
index f0796da..896478b 100644
--- a/kernel/Documentation/doc-guide/sphinx.rst
+++ b/kernel/Documentation/doc-guide/sphinx.rst
@@ -1,3 +1,5 @@
+.. _sphinxdoc:
+
Introduction
============
@@ -25,8 +27,7 @@
==============
The ReST markups currently used by the Documentation/ files are meant to be
-built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
-PDF outputs, it is recommended to use version 1.4.6 or upper.
+built with ``Sphinx`` version 1.3 or higher.
There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details.
@@ -35,15 +36,15 @@
and it is not uncommon that upgrading it or some other Python packages
on your machine would cause the documentation build to break.
-A way to get rid of that is to use a different version than the one shipped
-on your distributions. In order to do that, it is recommended to install
+A way to avoid that is to use a different version than the one shipped
+with your distributions. In order to do so, it is recommended to install
Sphinx inside a virtual environment, using ``virtualenv-3``
or ``virtualenv``, depending on how your distribution packaged Python 3.
.. note::
#) Sphinx versions below 1.5 don't work properly with Python's
- docutils version 0.13.1 or upper. So, if you're willing to use
+ docutils version 0.13.1 or higher. So, if you're willing to use
those versions, you should run ``pip install 'docutils==0.12'``.
#) It is recommended to use the RTD theme for html output. Depending
@@ -54,13 +55,13 @@
those expressions are written using LaTeX notation. It needs texlive
installed with amdfonts and amsmath in order to evaluate them.
-In summary, if you want to install Sphinx version 1.4.9, you should do::
+In summary, if you want to install Sphinx version 1.7.9, you should do::
- $ virtualenv sphinx_1.4
- $ . sphinx_1.4/bin/activate
- (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
+ $ virtualenv sphinx_1.7.9
+ $ . sphinx_1.7.9/bin/activate
+ (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
-After running ``. sphinx_1.4/bin/activate``, the prompt will change,
+After running ``. sphinx_1.7.9/bin/activate``, the prompt will change,
in order to indicate that you're using the new environment. If you
open a new shell, you need to rerun this command to enter again at
the virtual environment before building the documentation.
@@ -80,7 +81,7 @@
PDF and LaTeX builds
--------------------
-Such builds are currently supported only with Sphinx versions 1.4 and upper.
+Such builds are currently supported only with Sphinx versions 1.4 and higher.
For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
@@ -103,8 +104,8 @@
You should run:
sudo dnf install -y texlive-luatex85
- /usr/bin/virtualenv sphinx_1.4
- . sphinx_1.4/bin/activate
+ /usr/bin/virtualenv sphinx_1.7.9
+ . sphinx_1.7.9/bin/activate
pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
@@ -216,7 +217,7 @@
examples, etc.), use ``::`` for anything that doesn't really benefit
from syntax highlighting, especially short snippets. Use
``.. code-block:: <language>`` for longer code blocks that benefit
- from highlighting.
+ from highlighting. For a short snippet of code embedded in the text, use \`\`.
the C domain
@@ -240,11 +241,14 @@
The func-name (e.g. ioctl) remains in the output but the ref-name changed from
``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
-changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
+changed to ``VIDIOC_LOG_STATUS``.
-.. code-block:: rst
-
- :c:func:`VIDIOC_LOG_STATUS`
+Please note that there is no need to use ``c:func:`` to generate cross
+references to function documentation. Due to some Sphinx extension magic,
+the documentation build system will automatically turn a reference to
+``function()`` into a cross reference if an index entry for the given
+function name exists. If you see ``c:func:`` use in a kernel document,
+please feel free to remove it.
list tables
@@ -333,6 +337,23 @@
- column 3
+Cross-referencing
+-----------------
+
+Cross-referencing from one documentation page to another can be done by passing
+the path to the file starting from the Documentation folder.
+For example, to cross-reference to this page (the .rst extension is optional)::
+
+ See Documentation/doc-guide/sphinx.rst.
+
+If you want to use a relative path, you need to use Sphinx's ``doc`` directive.
+For example, referencing this page from the same directory would be done as::
+
+ See :doc:`sphinx`.
+
+For information on cross-referencing to kernel-doc functions or types, see
+Documentation/doc-guide/kernel-doc.rst.
+
.. _sphinx_kfigure:
Figures & Images
--
Gitblit v1.6.2