1.. include:: ../disclaimer-zh_CN.rst 2 3:Original: Documentation/doc-guide/sphinx.rst 4 5:������: ��������� Wu XiangCheng <bobwxc@email.cn> 6 7.. _sphinxdoc_zh: 8 9������ 10==== 11 12Linux������������ `Sphinx <http://www.sphinx-doc.org/>`_ ������ ``Documentation`` 13������ `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ ��������� 14������������������������������ ``make htmldocs`` ��� ``make pdfdocs`` ������������������HTML 15���PDF��������������������������������������� ``Documentation/output`` ��������������� 16 17reStructuredText������������������������������������������������������������������kernel-doc��������� 18������������������������������������������������������������kernel-doc��������������������������������� 19���������������������������������������������reStructuredText��������� 20 21��������������������������������������������������������� ``Documentation`` ��������������������������� 22������������������������������reStructuredText������������������������������������������ 23 24.. _sphinx_install_zh: 25 26������Sphinx 27========== 28 29Documentation/ ������ReST������������������sphinx1.7������������������������ 30 31������������������������������Sphinx������������������������������������ 32:ref:`sphinx-pre-install_zh` ��� 33 34������������������������������Sphinx������������������������������������������������������������������������ 35���������������Python��������������������������������������������������� 36 37��������������������������������������������������������������������������������������������������� 38``virtualenv-3`` ��� ``virtualenv`` ������������������������Sphinx��������������������������� 39������������Python3��� 40 41.. note:: 42 43 #) html������������������RTD���������������Sphinx������������������������������ 44 ``pip install sphinx_rtd_theme`` ��������������� 45 46 #) ������ReST������������������������������������Sphinx������������������������������������������ LaTeX 47 ���������������������������amsfonts���amsmath������������������������ 48 49������������������������Sphinx 2.4.4������������������:: 50 51 $ virtualenv sphinx_2.4.4 52 $ . sphinx_2.4.4/bin/activate 53 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt 54 55��������� ``. sphinx_2.4.4/bin/activate`` ��������������������������������������������������������� 56���������������������������������������shell��������������������������������������������������������������������� 57��������������������������� 58 59������������ 60-------- 61 62���������������������������������������������������������GraphViz���SVG������������������������ 63:ref:`sphinx_kfigure_zh` ������ 64 65������������������������������������������GraphViz���ImageMagick������������������������������������������ 66��������������������������������������������������������������������������� 67 68PDF���LaTeX������ 69-------------- 70 71������������Sphinx 2.4��������������������������������������� 72 73������PDF���LaTeX������������������ ``XeLaTeX`` 3.14159265��������������������������������������� 74��������� 75 76������������������������������������������������������������ ``texlive`` ������������������������������������ 77``XeLaTeX`` ��������������������������������� 78 79.. _sphinx-pre-install_zh: 80 81������Sphinx��������� 82---------------- 83 84������������������������������������Sphinx������������������������������������������������������������������������ 85������������������:: 86 87 $ ./scripts/sphinx-pre-install 88 Checking if the needed tools for Fedora release 26 (Twenty Six) are available 89 Warning: better to also install "texlive-luatex85". 90 You should run: 91 92 sudo dnf install -y texlive-luatex85 93 /usr/bin/virtualenv sphinx_2.4.4 94 . sphinx_2.4.4/bin/activate 95 pip install -r Documentation/sphinx/requirements.txt 96 97 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. 98 99������������������������������html���PDF������������������������������������������������������LaTeX��������� 100���������������������������������Python���������html��������������������������������������������������������� 101������������������������ 102 103������������������������������ 104 105``--no-pdf`` 106 107 ������PDF��������� 108 109``--no-virtualenv`` 110 111 ������Sphinx���������������������������Python��������������� 112 113Sphinx������ 114========== 115 116������������������������������������ ``make htmldocs`` ��� ``make pdfdocs`` ��������������������� 117��������������������� ``make help`` ��������������������������������������� ``Documentation/output`` 118��������������������������������� 119 120������������������������������������Sphinx��� ``sphinx-build`` ������������HTML������������������������ 121������Read the Docs Sphinx��������� ``sphinx_rtd_theme`` ������������PDF��������������������� 122``XeLaTeX`` ���������ImageMagick���https://www.imagemagick.org������ ``convert(1)`` ��� 123��������������������������������������������������������������� 124 125���������������������������Sphinx���������������make������ ``SPHINXOPTS`` ������������������ 126``make SPHINXOPTS=-v htmldocs`` ��������������������������� 127 128 129������������������������������������ ``make cleandocs`` ��� 130 131������������ 132======== 133 134������������������������������������ 135 1361. ��� ``Documentation`` ��������������������������� ``.rst`` ��������� 1372. ��� ``Documentation/index.rst`` ������Sphinx `������������`_ ��������������� 138 139.. _������������: http://www.sphinx-doc.org/en/stable/markup/toctree.html 140 141������������������������������������������������������������������������������������������������������������������ 142������������������������������������������������������������������������������������������������������������������ 143``Documentation/gpu`` ��������������������� ``.rst`` ��������������������������������������������� 144��������� ``index.rst`` ������������������������ ``toctree`` ������ 145 146��������� `Sphinx <http://www.sphinx-doc.org/>`_ ��� `reStructuredText 147<http://docutils.sourceforge.net/rst.html>`_ ������������������������������������������ 148���������Sphinx `reStructuredText ������`_ ������������������������reStructuredText��� 149������������������������ `Sphinx ������������������`_ ��� 150 151.. _reStructuredText ������: http://www.sphinx-doc.org/en/stable/rest.html 152.. _Sphinx ������������������: http://www.sphinx-doc.org/en/stable/markup/index.html 153 154��������������������������� 155------------------ 156 157������������������������������������������ 158 159* ������������������������������������reStructuredText������������������������������������������������ 160 ��������������������������������������������������������������������������������� 161 162* ������������������������reStructuredText������������������������������������ 163 164* ������������������������������������������������������������������ 165 166* ������������������������������������ 167 168 1. ``=`` ���������������������������:: 169 170 ======== 171 ������������ 172 ======== 173 174 2. ``=`` ���:: 175 176 ��������� 177 ====== 178 179 3. ``-`` ���:: 180 181 ��������� 182 ------ 183 184 4. ``~`` ������:: 185 186 ������������ 187 ~~~~~~~~ 188 189 ������RST��������������������������������������������������������������������������������������������������������� 190 ��������������������������������������������������������������������������������������������������������������� 191 192* ��������������������������������������������������������������������������� ``::`` ��������������������������� 193 ��������������������������������������� ``.. code-block:: <language>`` ��������������������������� 194 ��������������������������������������������������������������������������� \`\` ��� 195 196 197C��� 198--- 199 200**Sphinx C������Domain���** ���name c������������C API��������������������������������� 201 202.. code-block:: rst 203 204 .. c:function:: int ioctl( int fd, int request ) 205 206���������������C��������������������������������������������������������� ``open`` ��� ``ioctl`` ��������� 207��������������������������������������������� 208 209.. code-block:: rst 210 211 .. c:function:: int ioctl( int fd, int request ) 212 :name: VIDIOC_LOG_STATUS 213 214���������������������ioctl��������������������������������������������� ``ioctl`` ������ 215``VIDIOC_LOG_STATUS`` ��������������������������������� ``VIDIOC_LOG_STATUS`` ��� 216 217��������������������������� ``c:func:`` ������������������������������������������������Sphinx��������� 218������������������������������������������������������������������������������������������ ``function()`` 219��������������������������������������������������������������� ``c:func:`` ��������������������������� 220 221 222������ 223---- 224 225������������������ *���������* ��������� *���������* ���������������������������ASCII������������������������ 226������������������������������������������������������������������������������������������������������������������ 227���diff��������������������������������������������������������� 228 229*���������* ������������������������������������ *���������* ��������������������������������� 230 231* ������������������ ``cspan`` ��������������������������������������������� 232 233* ������������������ ``rspan`` ��������������������������������������������� 234 235* ��������������������������������������������������������������������������������������������� 236 ``:fill-cells:`` ��������������������������� *������������* ��������� *������������* ��������� 237 ��������������������������������������������������������������������������� 238 239��������� 240 241* ``:header-rows:`` [int] ��������������� 242* ``:stub-columns:`` [int] ��������������� 243* ``:widths:`` [[int] [int] ... ] ������ 244* ``:fill-cells:`` ������������������������������������������������������������������ 245 246��������� 247 248* ``:cspan:`` [int] ��������� 249* ``:rspan:`` [int] ��������� 250 251������������������������������������������������������������������������������ *���������* ��� *���������* ��� 252������������������������������ *���������* ������������������������ *comments* ��� ``..`` ������ 253*targets* ��������������������� ``:ref:`������������ <last row_zh>``` / :ref:`������������ 254<last row_zh>` ������ 255 256.. code-block:: rst 257 258 .. flat-table:: ������������ 259 :widths: 2 1 1 3 260 261 * - ������ ���1 262 - ������ ���2 263 - ������ ���3 264 - ������ ���4 265 266 * - ���1 267 - ������1.1 268 - ������1.2������������������ 269 270 * - ���2 271 - ������2.1 272 - :rspan:`1` :cspan:`1` ������2.2~3.3 273 274 * .. _`last row_zh`: 275 276 - ���3 277 278��������������� 279 280 .. flat-table:: ������������ 281 :widths: 2 1 1 3 282 283 * - ������ ���1 284 - ������ ���2 285 - ������ ���3 286 - ������ ���4 287 288 * - ���1 289 - ������1.1 290 - ������1.2������������������ 291 292 * - ���2 293 - ������2.1 294 - :rspan:`1` :cspan:`1` ������2.2~3.3 295 296 * .. _`last row_zh`: 297 298 - ���3 299 300������������ 301-------- 302 303������������������������������������������������������������������������������������������������������������������ 304������������������������������������������������������������������������Documentation/������������������������ 305��������������������������������������������������������������������������������� ``.rst`` ������������������ 306������:: 307 308 ������ Documentation/doc-guide/sphinx.rst ������������������������ 309 ��������� sphinx.rst ��������������������������������� 310 ��������� ../sphinx.rst ������������������������������ 311 312���������������������������������������������Sphinx��� ``doc`` ��������������������������������������������� 313���������������:: 314 315 ������ :doc:`sphinx������������������������������ <sphinx>`. 316 317������������������������������������������������������������������������������������������������������������������ 318������������������������������ ``:doc:`` ������������������������������������������ 319 320������������������kernel-doc������������������������������������ 321Documentation/doc-guide/kernel-doc.rst ��� 322 323.. _sphinx_kfigure_zh: 324 325������������ 326======== 327 328������������������������������������ ``kernel-figure`` ��� ``kernel-image`` ������������������ 329���������������������������������������������������������SVG���:ref:`svg_image_example_zh` ���:: 330 331 .. kernel-figure:: ../../../doc-guide/svg_image.svg 332 :alt: ������ SVG ������ 333 334 SVG ������������ 335 336.. _svg_image_example_zh: 337 338.. kernel-figure:: ../../../doc-guide/svg_image.svg 339 :alt: ������ SVG ������ 340 341 SVG ������������ 342 343������figure������image��������������� DOT ������������������������ 344 345* DOT���http://graphviz.org/pdf/dotguide.pdf 346* Graphviz���http://www.graphviz.org/content/dot-language 347 348������������������������:ref:`hello_dot_file_zh` ���:: 349 350 .. kernel-figure:: ../../../doc-guide/hello.dot 351 :alt: ��������������� 352 353 DOT ������ 354 355.. _hello_dot_file_zh: 356 357.. kernel-figure:: ../../../doc-guide/hello.dot 358 :alt: ��������������� 359 360 DOT ������ 361 362������������������������������������������Graphviz��� **DOT** ��� ``kernel-render`` ������������:: 363 364 .. kernel-render:: DOT 365 :alt: ��������� 366 :caption: ��������� **DOT** (Graphviz) ������ 367 368 digraph foo { 369 "���������" -> "������"; 370 } 371 372������������������������������������������������������Graphviz��������������������������������������������������� 373��������������� *���������* ���������:ref:`hello_dot_render_zh` ������ 374 375.. _hello_dot_render_zh: 376 377.. kernel-render:: DOT 378 :alt: ��������� 379 :caption: ��������� **DOT** (Graphviz) ������ 380 381 digraph foo { 382 "���������" -> "������"; 383 } 384 385*render* ������������ *figure* ��������������������������������������������� ``caption`` ��������� 386``caption`` ������������������������ *figure* ��������������������������������� *image* ��������� 387��������������������������������������� ``caption`` ���:ref:`hello_svg_render_zh` ������ 388 389��������� **SVG**:: 390 391 .. kernel-render:: SVG 392 :caption: ��������� **SVG** ������ 393 :alt: ������������ 394 395 <?xml version="1.0" encoding="UTF-8"?> 396 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> 397 ... 398 </svg> 399 400.. _hello_svg_render_zh: 401 402.. kernel-render:: SVG 403 :caption: ��������� **SVG** ������ 404 :alt: ������������ 405 406 <?xml version="1.0" encoding="UTF-8"?> 407 <svg xmlns="http://www.w3.org/2000/svg" 408 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> 409 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> 410 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> 411 </svg> 412 413