.. | .. |
---|
| 1 | +.. _sphinxdoc: |
---|
| 2 | + |
---|
1 | 3 | Introduction |
---|
2 | 4 | ============ |
---|
3 | 5 | |
---|
.. | .. |
---|
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 |
---|