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
56 (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
64 ------------
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
155 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
167 under ``Documentation/doc-guide`` by running
168 ``make SPHINXDIRS=doc-guide htmldocs``.
179 -----------------------
218 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
232 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
233 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
236 ------------------------------------------------
264 3. ``-`` for sections::
267 -------
282 ``.. code-block:: <language>`` for longer code blocks that benefit
287 ------------
292 .. code-block:: rst
296 The C domain of the kernel-doc has some additional features. E.g. you can
300 .. code-block:: rst
305 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
317 ------
329 The list-table formats can be useful for tables that are not easily laid
330 out in the usual Sphinx ASCII-art formats. These formats are nearly
331 impossible for readers of the plain-text documents to understand, though,
335 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
338 * column-span: with the role ``cspan`` a cell can be extended through
341 * row-span: with the role ``rspan`` a cell can be extended through
345 side of that table-row. With Option ``:fill-cells:`` this behavior can
351 * ``:header-rows:`` [int] count of header rows
352 * ``:stub-columns:`` [int] count of stub columns
354 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
362 list is the *table-row*. In the *table-row* there is only one markup allowed,
363 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
367 .. code-block:: rst
369 .. flat-table:: table title
372 * - head col 1
373 - head col 2
374 - head col 3
375 - head col 4
377 * - row 1
378 - field 1.1
379 - field 1.2 with autospan
381 * - row 2
382 - field 2.1
383 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
387 - row 3
391 .. flat-table:: table title
394 * - head col 1
395 - head col 2
396 - head col 3
397 - head col 4
399 * - row 1
400 - field 1.1
401 - field 1.2 with autospan
403 * - row 2
404 - field 2.1
405 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
409 - row 3
411 Cross-referencing
412 -----------------
414 Cross-referencing from one documentation page to another can be done simply by
417 "Documentation/". For example, to cross-reference to this page, all the
421 See Documentation/doc-guide/sphinx.rst. This always works.
428 See :doc:`my custom link text for document sphinx <sphinx>`.
435 For information on cross-referencing to kernel-doc functions or types, see
436 Documentation/doc-guide/kernel-doc.rst.
452 If you want to add an image, you should use the ``kernel-figure`` and
453 ``kernel-image`` directives. E.g. to insert a figure with a scalable
456 .. kernel-figure:: svg_image.svg
463 .. kernel-figure:: svg_image.svg
471 * Graphviz: http://www.graphviz.org/content/dot-language
475 .. kernel-figure:: hello.dot
482 .. kernel-figure:: hello.dot
488 ``kernel-render`` directives.::
490 .. kernel-render:: DOT
495 "bar" -> "baz";
500 *literal-block* (:ref:`hello_dot_render`).
504 .. kernel-render:: DOT
509 "bar" -> "baz";
519 .. kernel-render:: SVG
521 :alt: so-nw-arrow
523 <?xml version="1.0" encoding="UTF-8"?>
530 .. kernel-render:: SVG
532 :alt: so-nw-arrow
534 <?xml version="1.0" encoding="UTF-8"?>
537 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>