OwlBurst/Ponysearch
1
0
Fork 0
forked from Ponysearch/Ponysearch
Code Pull requests Activity

doc: add content to reST primer (WIP) // linuxdoc

Browse source 
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-19 23:36:53 +01:00
parent bee19a76f7
commit e1566e68aa
6 changed files with 254 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/_themes/searx/static/searx.css vendored
View file

@ -29,6 +29,14 @@ p.sidebar-title, .sidebar p {
} }
div.admonition,
div.topic {
background-color: #fafafa;
margin: 8px 0px;
padding: 1em;
border: none;
}
/* admonitions with (rendered) reST markup examples (:class: rst-example) /* admonitions with (rendered) reST markup examples (:class: rst-example)
* *
* .. admonition:: title of the example * .. admonition:: title of the example

11
docs/conf.py
View file

@ -20,6 +20,7 @@ highlight_language = 'none'
master_doc = "index" master_doc = "index"
source_suffix = '.rst' source_suffix = '.rst'
numfig = True
# usage:: lorem :patch:`f373169` ipsum # usage:: lorem :patch:`f373169` ipsum
extlinks = {} extlinks = {}
@ -35,6 +36,8 @@ extlinks['search'] = (SEARX_URL + '/%s', '#')
extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ') extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ') extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ')
extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '') extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '')
#extlinks['role'] = (
# 'https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-%s', '')
extlinks['duref'] = ( extlinks['duref'] = (
'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') 'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '')
extlinks['durole'] = ( extlinks['durole'] = (
@ -49,6 +52,12 @@ extensions = [
"sphinx.ext.intersphinx", "sphinx.ext.intersphinx",
"pallets_sphinx_themes", "pallets_sphinx_themes",
"sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst
'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive.
'linuxdoc.rstKernelDoc', # Implementation of the 'kernel-doc' reST-directive.
'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive.
'linuxdoc.manKernelDoc', # Implementation of the 'kernel-doc-man' builder
'linuxdoc.cdomain', # Replacement for the sphinx c-domain.
'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling.
] ]
intersphinx_mapping = { intersphinx_mapping = {
@ -56,6 +65,8 @@ intersphinx_mapping = {
"flask": ("https://flask.palletsprojects.com/", None), "flask": ("https://flask.palletsprojects.com/", None),
# "werkzeug": ("https://werkzeug.palletsprojects.com/", None), # "werkzeug": ("https://werkzeug.palletsprojects.com/", None),
"jinja": ("https://jinja.palletsprojects.com/", None), "jinja": ("https://jinja.palletsprojects.com/", None),
"linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
"sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
} }
issues_github_path = "asciimoo/searx" issues_github_path = "asciimoo/searx"

3
docs/dev/hello.dot Normal file
View file

@ -0,0 +1,3 @@
graph G {
Hello -- World
}

311
docs/dev/reST.rst
View file

@ -18,11 +18,26 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
------ ------
.. sidebar:: Further reading
- Sphinx-Primer_
- `Sphinx markup constructs`_
- reST_, docutils_, `docutils FAQ`_
- Sphinx_, `sphinx-doc FAQ`_
- `sphinx config`_, doctree_
- `sphinx cross references`_
- linuxdoc_
- intersphinx_
- `Sphinx's autodoc`_
- `Sphinx's Python domain`_, `Sphinx's C domain`_
.. contents:: Contents .. contents:: Contents
:depth: 3 :depth: 3
:local: :local:
:backlinks: entry :backlinks: entry
------
Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is
used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_. used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
@ -55,18 +70,6 @@ To be more concrete what a *point of view* means. In the (:origin:`docs`)
folder we have three sections (and the *blog* folder), each dedicate to a folder we have three sections (and the *blog* folder), each dedicate to a
different group of audience. different group of audience.
.. sidebar:: Further reading
- Sphinx-Primer_
- `Sphinx markup constructs`_
- reST_, docutils_, `docutils FAQ`_
- Sphinx_, `sphinx-doc FAQ`_
- `sphinx config`_, doctree_
- `sphinx cross references`_
- intersphinx_
- `Sphinx's autodoc`_
- `Sphinx's Python domain`_, `Sphinx's C domain`_
User's POV: :origin:`docs/user` User's POV: :origin:`docs/user`
A typical user knows about search engines and might have heard about A typical user knows about search engines and might have heard about
meta crawlers and privacy. meta crawlers and privacy.
@ -100,25 +103,52 @@ Basic inline markup
inline markup delimiters, they have to be escaped with a backslash (``\*foo is inline markup delimiters, they have to be escaped with a backslash (``\*foo is
a pointer``). a pointer``).
.. _reST basic structure:
Roles Basic article structure
===== =======================
A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of The basic structure of an article makes use of heading adornments to markup
explicit markup. It signifies that that the enclosed text should be interpreted chapter, sections and subsections.
in a specific way. The general syntax is ``:rolename:`content```.
Docutils supports the following roles: #. ``=`` with overline for document title
#. ``=`` for chapters
#. ``-`` for sections
#. ``~`` for subsections
* :durole:`emphasis` -- equivalent of ``*emphasis*`` .. _reST template:
* :durole:`strong` -- equivalent of ``**strong**``
* :durole:`literal` -- equivalent of ````literal````
* :durole:`subscript` -- subscript text
* :durole:`superscript` -- superscript text
* :durole:`title-reference` -- for titles of books, periodicals, and other
materials
Refer to `Sphinx Roles`_ for roles added by Sphinx. .. admonition:: reST template
:class: rst-example
.. code:: reST
.. _document title:
==============
Document title
==============
Lorem ipsum dolor sit amet, consectetur adipisici elit ..
Further read :ref:`chapter title`.
.. _chapter title:
Chapters
========
Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquid ex ea commodi consequat ...
Section
-------
lorem ..
Subsection
~~~~~~~~~~
lorem ..
Anchors & Links Anchors & Links
@ -196,42 +226,29 @@ smart references
---------------- ----------------
With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
content becomes smart. To refer ... content becomes smart.
sphinx.ext.extlinks_: ========================== ================================== ====================================
refer ... rendered example markup
:project's wiki article: :wiki:`Searx-instances` ========================== ================================== ====================================
:to docs public URL: :docs:`dev/reST.html` :rst:role:`rfc` :rfc:`822` ``:rfc:`822```
:files & folders from origin: :origin:`docs/dev/reST.rst` :rst:role:`pep` :pep:`8` ``:pep:`8```
:a pull request: :pull:`1756` sphinx.ext.extlinks_
:a patch: :patch:`af2cae6` --------------------------------------------------------------------------------------------------
:a PyPi package: :pypi:`searx` project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances```
:a manual page man: :man:`bash` to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
.. code:: reST pull request :pull:`1756` ``:pull:`1756```
patch :patch:`af2cae6` ``:patch:`af2cae6```
:project's wiki article: :wiki:`Searx-instances` PyPi package :pypi:`searx` ``:pypi:`searx```
:to docs public URL: :docs:`dev/reST.html` manual page man :man:`bash` ``:man:`bash```
:files & folders from origin: :origin:`docs/dev/reST.rst` intersphinx_
:a pull request: :pull:`1756` --------------------------------------------------------------------------------------------------
:a patch: :patch:`af2cae6` external anchor :ref:`python:and` ``:ref:`python:and```
:a PyPi package: :pypi:`searx` external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
:a manual page man: :man:`bash` python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
========================== ================================== ====================================
intersphinx_:
:external anchor: :ref:`python:and`
:external doc anchor: :doc:`jinja:templates`
:python code object: :py:obj:`datetime.datetime`
:flask code object: webapp is a :py:obj:`flask.Flask` app
.. code:: reST
:external anchor: :ref:`python:and`
:external doc anchor: :doc:`jinja:templates`
:python code object: :py:obj:`datetime.datetime`
:flask code object: webapp is a :py:obj:`flask.Flask` app
Intersphinx is configured in :origin:`docs/conf.py`: Intersphinx is configured in :origin:`docs/conf.py`:
@ -242,6 +259,8 @@ Intersphinx is configured in :origin:`docs/conf.py`:
"python": ("https://docs.python.org/3/", None), "python": ("https://docs.python.org/3/", None),
"flask": ("https://flask.palletsprojects.com/", None), "flask": ("https://flask.palletsprojects.com/", None),
"jinja": ("https://jinja.palletsprojects.com/", None), "jinja": ("https://jinja.palletsprojects.com/", None),
"linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
"sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
} }
@ -252,52 +271,163 @@ To list all anchors of the inventory (e.g. ``python``) use:
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
.. _reST basic structure: Roles
=====
Basic article structure A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
======================= explicit markup. It signifies that that the enclosed text should be interpreted
in a specific way. The general syntax is ``:rolename:`content```.
The basic structure of an article makes use of heading adornments to markup ========================== ================================== ====================================
chapter, sections and subsections. role rendered example markup
========================== ================================== ====================================
:rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
:rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
:rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
:rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
:rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
:rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
:rst:role:`command` :command:`ls -la` ``:command:`ls -la```
:durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
:durole:`strong` :strong:`bold` ``:strong:`bold```
:durole:`literal` :literal:`foo()` ``:literal:`foo()```
:durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
:durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
:durole:`title-reference` :title:`Time` ``:title:`Time```
========================== ================================== ====================================
#. ``=`` with overline for document title Refer to `Sphinx Roles`_ for roles added by Sphinx.
#. ``=`` for chapters
#. ``-`` for sections
#. ``~`` for subsections
.. _reST template:
.. admonition:: reST template Figures & Images
:class: rst-example ================
Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
scalable in sense of the build process. Normally in absence of a converter
tool, the build process will break. From the authors POV it’s annoying to care
about the build process when handling with images, especially since he has no
access to the build process. With :ref:`linuxdoc:kfigure` the build process
continues and scales output quality in dependence of installed image processors.
If you want to add an image, you should use the ``kernel-figure`` and
``kernel-image`` directives. E.g. to insert a figure with a scalable image
format use SVG (:ref:`svg_image_example`):
.. code:: reST .. code:: reST
.. _document title: .. _svg image example:
============== .. kernel-figure:: svg_image.svg
Document title :alt: simple SVG image
==============
Lorem ipsum dolor sit amet, consectetur adipisici elit .. SVG image example
Further read :ref:`chapter title`.
.. _chapter title: .. _svg image example:
Chapters .. kernel-figure:: svg_image.svg
======== :alt: simple SVG image
Ut enim ad minim veniam, quis nostrud exercitation ullamco SVG image example
laboris nisi ut aliquid ex ea commodi consequat ...
Section DOT files (aka Graphviz)
------- ------------------------
lorem .. The kernel figure (and image) directive support **DOT** formated files, see
Subsection * DOT: http://graphviz.org/pdf/dotguide.pdf
~~~~~~~~~~ * Graphviz: http://www.graphviz.org/content/dot-language
A simple example (:ref:`hello_dot_file`):
.. code:: reST
.. kernel-figure:: hello.dot
:alt: hello world
DOT's hello world example
.. admonition:: hello.dot
:class: rst-example
.. kernel-figure:: hello.dot
:alt: hello world
DOT's hello world example
``kernel-render`` DOT
---------------------
Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
``kernel-render`` directives.
.. code:: reST
.. kernel-render:: DOT markup
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code
digraph foo {
"bar" -> "baz";
}
How this will be rendered depends on the installed tools. If Graphviz is
installed, you will see an vector image. If not the raw markup is inserted as
*literal-block* (:ref:`hello_dot_render`).
.. admonition:: DOT markup
:class: rst-example
.. _hello_dot_render:
.. kernel-render:: DOT
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code
digraph foo {
"bar" -> "baz";
}
The *render* directive has all the options known from the *figure* directive,
plus option ``caption``. If ``caption`` has a value, a *figure* node is
inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
you want to refer it (:ref:`hello_svg_render`).
``kernel-render`` SVG
---------------------
.. code:: reST
.. kernel-render:: SVG markup
:caption: Embedded **SVG** markup
:alt: so-nw-arrow
..
.. code:: xml
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
</svg>
.. admonition:: SVG markup
:class: rst-example
.. _hello_svg_render:
.. kernel-render:: SVG
:caption: Embedded **SVG** markup
:alt: so-nw-arrow
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
</svg>
lorem ..
.. _reST lists: .. _reST lists:
@ -489,3 +619,4 @@ Further list blocks
http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
.. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils: http://docutils.sourceforge.net/docs/index.html
.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
.. _linuxdoc: https://return42.github.io/linuxdoc

10
docs/dev/svg_image.svg Normal file
View file

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg -->
<svg xmlns="http://www.w3.org/2000/svg"
version="1.1" baseProfile="full"
width="70px" height="40px" viewBox="0 0 700 400">
<line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/>
<rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/>
<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 580 B

1
requirements-dev.txt
View file

@ -11,3 +11,4 @@ transifex-client==0.12.2
unittest2==1.1.0 unittest2==1.1.0
zope.testrunner==4.5.1 zope.testrunner==4.5.1
selenium==3.141.0 selenium==3.141.0
linuxdoc @ git+http://github.com/return42/linuxdoc.git