Lines Matching +full:custom +full:- +full:rtd
12 .. _Sphinx: http://www.sphinx-doc.org/
16 documentation comments, or kernel-doc comments, from source files. Usually these
18 kernel-doc comments have some special structure and formatting, but beyond that
34 :ref:`sphinx-pre-install` for further details.
42 Sphinx inside a virtual environment, using ``virtualenv-3``
47 #) It is recommended to use the RTD theme for html output. Depending
55 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
63 ------------
75 --------------------
86 ------------------------
95 The former was the only option for pre-6.1 kernel documentation and it
103 .. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgm…
104 .. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.math…
106 .. _sphinx-pre-install:
109 --------------------------------
115 $ ./scripts/sphinx-pre-install
117 Warning: better to also install "texlive-luatex85".
120 sudo dnf install -y texlive-luatex85
123 pip install -r Documentation/sphinx/requirements.txt
125 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
134 ``--no-pdf``
137 ``--no-virtualenv``
147 format-specific subdirectories under ``Documentation/output``.
149 To generate documentation, Sphinx (``sphinx-build``) must obviously be
157 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
167 If the theme is not available, it will fall-back to the classic one.
173 under ``Documentation/doc-guide`` by running
174 ``make SPHINXDIRS=doc-guide htmldocs``.
185 -----------------------
224 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
238 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
239 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
242 ------------------------------------------------
270 3. ``-`` for sections::
273 -------
288 ``.. code-block:: <language>`` for longer code blocks that benefit
293 ------------
298 .. code-block:: rst
302 The C domain of the kernel-doc has some additional features. E.g. you can
306 .. code-block:: rst
311 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
324 -----------
326 The list-table formats can be useful for tables that are not easily laid
327 out in the usual Sphinx ASCII-art formats. These formats are nearly
328 impossible for readers of the plain-text documents to understand, though,
332 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
335 * column-span: with the role ``cspan`` a cell can be extended through
338 * row-span: with the role ``rspan`` a cell can be extended through
342 side of that table-row. With Option ``:fill-cells:`` this behavior can
348 * ``:header-rows:`` [int] count of header rows
349 * ``:stub-columns:`` [int] count of stub columns
351 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
359 list is the *table-row*. In the *table-row* there is only one markup allowed,
360 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
364 .. code-block:: rst
366 .. flat-table:: table title
369 * - head col 1
370 - head col 2
371 - head col 3
372 - head col 4
374 * - row 1
375 - field 1.1
376 - field 1.2 with autospan
378 * - row 2
379 - field 2.1
380 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
384 - row 3
388 .. flat-table:: table title
391 * - head col 1
392 - head col 2
393 - head col 3
394 - head col 4
396 * - row 1
397 - field 1.1
398 - field 1.2 with autospan
400 * - row 2
401 - field 2.1
402 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
406 - row 3
408 Cross-referencing
409 -----------------
411 Cross-referencing from one documentation page to another can be done simply by
414 "Documentation/". For example, to cross-reference to this page, all the
418 See Documentation/doc-guide/sphinx.rst. This always works.
425 See :doc:`my custom link text for document sphinx <sphinx>`.
432 For information on cross-referencing to kernel-doc functions or types, see
433 Documentation/doc-guide/kernel-doc.rst.
440 If you want to add an image, you should use the ``kernel-figure`` and
441 ``kernel-image`` directives. E.g. to insert a figure with a scalable
444 .. kernel-figure:: svg_image.svg
451 .. kernel-figure:: svg_image.svg
459 * Graphviz: http://www.graphviz.org/content/dot-language
463 .. kernel-figure:: hello.dot
470 .. kernel-figure:: hello.dot
476 ``kernel-render`` directives.::
478 .. kernel-render:: DOT
483 "bar" -> "baz";
488 *literal-block* (:ref:`hello_dot_render`).
492 .. kernel-render:: DOT
497 "bar" -> "baz";
507 .. kernel-render:: SVG
509 :alt: so-nw-arrow
511 <?xml version="1.0" encoding="UTF-8"?>
518 .. kernel-render:: SVG
520 :alt: so-nw-arrow
522 <?xml version="1.0" encoding="UTF-8"?>
525 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>