@@ -18,11 +18,26 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
1818
1919------
2020
21+.. sidebar:: Further reading
22+
23+ - Sphinx-Primer_
24+ - `Sphinx markup constructs`_
25+ - reST_, docutils_, `docutils FAQ`_
26+ - Sphinx_, `sphinx-doc FAQ`_
27+ - `sphinx config`_, doctree_
28+ - `sphinx cross references`_
29+ - linuxdoc_
30+ - intersphinx_
31+ - `Sphinx's autodoc`_
32+ - `Sphinx's Python domain`_, `Sphinx's C domain`_
33+
2134.. contents:: Contents
2235 :depth: 3
2336 :local:
2437 :backlinks: entry
2538
39+------
40+
2641Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is
2742used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
2843
@@ -55,18 +70,6 @@ To be more concrete what a *point of view* means. In the (:origin:`docs`)
5570folder we have three sections (and the *blog* folder), each dedicate to a
5671different group of audience.
5772
58−.. sidebar:: Further reading
59−
60− - Sphinx-Primer_
61− - `Sphinx markup constructs`_
62− - reST_, docutils_, `docutils FAQ`_
63− - Sphinx_, `sphinx-doc FAQ`_
64− - `sphinx config`_, doctree_
65− - `sphinx cross references`_
66− - intersphinx_
67− - `Sphinx's autodoc`_
68− - `Sphinx's Python domain`_, `Sphinx's C domain`_
69−
7073User's POV: :origin:`docs/user`
7174 A typical user knows about search engines and might have heard about
7275 meta crawlers and privacy.
@@ -100,25 +103,52 @@ Basic inline markup
100103 inline markup delimiters, they have to be escaped with a backslash (``\*foo is
101104 a pointer``).
102105
106+.. _reST basic structure:
103107
104−Roles
105−=====
108+Basic article structure
109+=======================
106110
107−A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
108−explicit markup. It signifies that that the enclosed text should be interpreted
109−in a specific way. The general syntax is ``:rolename:`content```.
111+The basic structure of an article makes use of heading adornments to markup
112+chapter, sections and subsections.
113+
114+#. ``=`` with overline for document title
115+#. ``=`` for chapters
116+#. ``-`` for sections
117+#. ``~`` for subsections
118+
119+.. _reST template:
120+
121+.. admonition:: reST template
122+ :class: rst-example
110123
111−Docutils supports the following roles:
124+ .. code:: reST
112125
113−* :durole:`emphasis` -- equivalent of ``*emphasis*``
114−* :durole:`strong` -- equivalent of ``**strong**``
115−* :durole:`literal` -- equivalent of ````literal````
116−* :durole:`subscript` -- subscript text
117−* :durole:`superscript` -- superscript text
118−* :durole:`title-reference` -- for titles of books, periodicals, and other
119− materials
126+ .. _document title:
120127
121−Refer to `Sphinx Roles`_ for roles added by Sphinx.
128+ ==============
129+ Document title
130+ ==============
131+
132+ Lorem ipsum dolor sit amet, consectetur adipisici elit ..
133+ Further read :ref:`chapter title`.
134+
135+ .. _chapter title:
136+
137+ Chapters
138+ ========
139+
140+ Ut enim ad minim veniam, quis nostrud exercitation ullamco
141+ laboris nisi ut aliquid ex ea commodi consequat ...
142+
143+ Section
144+ -------
145+
146+ lorem ..
147+
148+ Subsection
149+ ~~~~~~~~~~
150+
151+ lorem ..
122152
123153
124154Anchors & Links
@@ -196,42 +226,29 @@ smart references
196226----------------
197227
198228With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
199−content becomes smart. To refer ...
200−
201−sphinx.ext.extlinks_:
202−
203−:project's wiki article: :wiki:`Searx-instances`
204−:to docs public URL: :docs:`dev/reST.html`
205−:files & folders from origin: :origin:`docs/dev/reST.rst`
206−:a pull request: :pull:`1756`
207−:a patch: :patch:`af2cae6`
208−:a PyPi package: :pypi:`searx`
209−:a manual page man: :man:`bash`
210−
211−.. code:: reST
212−
213− :project's wiki article: :wiki:`Searx-instances`
214− :to docs public URL: :docs:`dev/reST.html`
215− :files & folders from origin: :origin:`docs/dev/reST.rst`
216− :a pull request: :pull:`1756`
217− :a patch: :patch:`af2cae6`
218− :a PyPi package: :pypi:`searx`
219− :a manual page man: :man:`bash`
220−
221−
222−intersphinx_:
223−
224− :external anchor: :ref:`python:and`
225− :external doc anchor: :doc:`jinja:templates`
226− :python code object: :py:obj:`datetime.datetime`
227− :flask code object: webapp is a :py:obj:`flask.Flask` app
228−
229−.. code:: reST
230−
231− :external anchor: :ref:`python:and`
232− :external doc anchor: :doc:`jinja:templates`
233− :python code object: :py:obj:`datetime.datetime`
234− :flask code object: webapp is a :py:obj:`flask.Flask` app
229+content becomes smart.
230+
231+========================== ================================== ====================================
232+refer ... rendered example markup
233+========================== ================================== ====================================
234+:rst:role:`rfc` :rfc:`822` ``:rfc:`822```
235+:rst:role:`pep` :pep:`8` ``:pep:`8```
236+sphinx.ext.extlinks_
237+--------------------------------------------------------------------------------------------------
238+project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances```
239+to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
240+files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
241+pull request :pull:`1756` ``:pull:`1756```
242+patch :patch:`af2cae6` ``:patch:`af2cae6```
243+PyPi package :pypi:`searx` ``:pypi:`searx```
244+manual page man :man:`bash` ``:man:`bash```
245+intersphinx_
246+--------------------------------------------------------------------------------------------------
247+external anchor :ref:`python:and` ``:ref:`python:and```
248+external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
249+python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
250+flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
251+========================== ================================== ====================================
235252
236253
237254Intersphinx is configured in :origin:`docs/conf.py`:
@@ -242,6 +259,8 @@ Intersphinx is configured in :origin:`docs/conf.py`:
242259 "python": ("https://docs.python.org/3/", None),
243260 "flask": ("https://flask.palletsprojects.com/", None),
244261 "jinja": ("https://jinja.palletsprojects.com/", None),
262+ "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
263+ "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
245264 }
246265
247266
@@ -252,52 +271,163 @@ To list all anchors of the inventory (e.g. ``python``) use:
252271 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
253272
254273
255−.. _reST basic structure:
274+Roles
275+=====
256276
257−Basic article structure
258−=======================
277+A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
278+explicit markup. It signifies that that the enclosed text should be interpreted
279+in a specific way. The general syntax is ``:rolename:`content```.
259280
260−The basic structure of an article makes use of heading adornments to markup
261−chapter, sections and subsections.
281+========================== ================================== ====================================
282+role rendered example markup
283+========================== ================================== ====================================
284+:rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
285+:rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
286+:rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
287+:rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
288+:rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
289+:rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
290+:rst:role:`command` :command:`ls -la` ``:command:`ls -la```
291+:durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
292+:durole:`strong` :strong:`bold` ``:strong:`bold```
293+:durole:`literal` :literal:`foo()` ``:literal:`foo()```
294+:durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
295+:durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
296+:durole:`title-reference` :title:`Time` ``:title:`Time```
297+========================== ================================== ====================================
262298
263−#. ``=`` with overline for document title
264−#. ``=`` for chapters
265−#. ``-`` for sections
266−#. ``~`` for subsections
299+Refer to `Sphinx Roles`_ for roles added by Sphinx.
267300
268−.. _reST template:
269301
270−.. admonition:: reST template
302+Figures & Images
303+================
304+
305+Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
306+scalable in sense of the build process. Normally in absence of a converter
307+tool, the build process will break. From the authors POV it’s annoying to care
308+about the build process when handling with images, especially since he has no
309+access to the build process. With :ref:`linuxdoc:kfigure` the build process
310+continues and scales output quality in dependence of installed image processors.
311+
312+If you want to add an image, you should use the ``kernel-figure`` and
313+``kernel-image`` directives. E.g. to insert a figure with a scalable image
314+format use SVG (:ref:`svg_image_example`):
315+
316+.. code:: reST
317+
318+ .. _svg image example:
319+
320+ .. kernel-figure:: svg_image.svg
321+ :alt: simple SVG image
322+
323+ SVG image example
324+
325+.. _svg image example:
326+
327+.. kernel-figure:: svg_image.svg
328+ :alt: simple SVG image
329+
330+ SVG image example
331+
332+DOT files (aka Graphviz)
333+------------------------
334+
335+The kernel figure (and image) directive support **DOT** formated files, see
336+
337+* DOT: http://graphviz.org/pdf/dotguide.pdf
338+* Graphviz: http://www.graphviz.org/content/dot-language
339+
340+A simple example (:ref:`hello_dot_file`):
341+
342+.. code:: reST
343+
344+ .. kernel-figure:: hello.dot
345+ :alt: hello world
346+
347+ DOT's hello world example
348+
349+.. admonition:: hello.dot
271350 :class: rst-example
272351
273− .. code:: reST
352+ .. kernel-figure:: hello.dot
353+ :alt: hello world
274354
275− .. _document title:
355+ DOT's hello world example
276356
277− ==============
278− Document title
279− ==============
357+``kernel-render`` DOT
358+---------------------
280359
281− Lorem ipsum dolor sit amet, consectetur adipisici elit ..
282− Further read :ref:`chapter title`.
360+Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
361+``kernel-render`` directives.
283362
284− .. _chapter title:
363+.. code:: reST
285364
286− Chapters
287− ========
365+ .. kernel-render:: DOT markup
366+ :alt: foobar digraph
367+ :caption: Embedded **DOT** (Graphviz) code
288368
289− Ut enim ad minim veniam, quis nostrud exercitation ullamco
290− laboris nisi ut aliquid ex ea commodi consequat ...
369+ digraph foo {
370+ "bar" -> "baz";
371+ }
291372
292− Section
293− -------
373+How this will be rendered depends on the installed tools. If Graphviz is
374+installed, you will see an vector image. If not the raw markup is inserted as
375+*literal-block* (:ref:`hello_dot_render`).
294376
295− lorem ..
377+.. admonition:: DOT markup
378+ :class: rst-example
296379
297− Subsection
298− ~~~~~~~~~~
380+ .. _hello_dot_render:
381+
382+ .. kernel-render:: DOT
383+ :alt: foobar digraph
384+ :caption: Embedded **DOT** (Graphviz) code
385+
386+ digraph foo {
387+ "bar" -> "baz";
388+ }
389+
390+The *render* directive has all the options known from the *figure* directive,
391+plus option ``caption``. If ``caption`` has a value, a *figure* node is
392+inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
393+you want to refer it (:ref:`hello_svg_render`).
394+
395+
396+``kernel-render`` SVG
397+---------------------
398+
399+.. code:: reST
400+
401+ .. kernel-render:: SVG markup
402+ :caption: Embedded **SVG** markup
403+ :alt: so-nw-arrow
404+..
405+
406+ .. code:: xml
407+
408+ <?xml version="1.0" encoding="UTF-8"?>
409+ <svg xmlns="http://www.w3.org/2000/svg"
410+ version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
411+ <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
412+ <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
413+ </svg>
414+
415+.. admonition:: SVG markup
416+ :class: rst-example
417+
418+ .. _hello_svg_render:
419+
420+ .. kernel-render:: SVG
421+ :caption: Embedded **SVG** markup
422+ :alt: so-nw-arrow
423+
424+ <?xml version="1.0" encoding="UTF-8"?>
425+ <svg xmlns="http://www.w3.org/2000/svg"
426+ version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
427+ <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
428+ <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
429+ </svg>
299430
300− lorem ..
301431
302432.. _reST lists:
303433
@@ -489,3 +619,4 @@ Further list blocks
489619 http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
490620.. _docutils: http://docutils.sourceforge.net/docs/index.html
491621.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
622+.. _linuxdoc: https://return42.github.io/linuxdoc