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