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)
*
* .. admonition:: title of the example

11
docs/conf.py
View file

@ -20,6 +20,7 @@ highlight_language = 'none'
master_doc = "index"
source_suffix = '.rst'
numfig = True
# usage:: lorem :patch:`f373169` ipsum
extlinks = {}
@ -35,6 +36,8 @@ extlinks['search'] = (SEARX_URL + '/%s', '#')
extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ')
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'] = (
'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '')
extlinks['durole'] = (
@ -49,6 +52,12 @@ extensions = [
"sphinx.ext.intersphinx",
"pallets_sphinx_themes",
"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 = {
@ -56,6 +65,8 @@ intersphinx_mapping = {
"flask": ("https://flask.palletsprojects.com/", None),
# "werkzeug": ("https://werkzeug.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"

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
:depth: 3
:local:
:backlinks: entry
------
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]`_.
@ -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
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`
A typical user knows about search engines and might have heard about
meta crawlers and privacy.
@ -100,25 +103,52 @@ Basic inline markup
inline markup delimiters, they have to be escaped with a backslash (``\*foo is
a pointer``).
.. _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.
Docutils supports the following roles:
#. ``=`` with overline for document title
#. ``=`` for chapters
#. ``-`` for sections
#. ``~`` for subsections
* :durole:`emphasis` -- equivalent of ``*emphasis*``
* :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
.. _reST template:
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
@ -196,42 +226,29 @@ smart references
----------------
With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
content becomes smart. To refer ...
content becomes smart.
sphinx.ext.extlinks_:
:project's wiki article: :wiki:`Searx-instances`
:to docs public URL: :docs:`dev/reST.html`
:files & folders from origin: :origin:`docs/dev/reST.rst`
:a pull request: :pull:`1756`
:a patch: :patch:`af2cae6`
:a PyPi package: :pypi:`searx`
:a manual page man: :man:`bash`
.. code:: reST
:project's wiki article: :wiki:`Searx-instances`
:to docs public URL: :docs:`dev/reST.html`
:files & folders from origin: :origin:`docs/dev/reST.rst`
:a pull request: :pull:`1756`
:a patch: :patch:`af2cae6`
:a PyPi package: :pypi:`searx`
:a manual page man: :man:`bash`
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
========================== ================================== ====================================
refer ... rendered example markup
========================== ================================== ====================================
:rst:role:`rfc` :rfc:`822` ``:rfc:`822```
:rst:role:`pep` :pep:`8` ``:pep:`8```
sphinx.ext.extlinks_
--------------------------------------------------------------------------------------------------
project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances```
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```
pull request :pull:`1756` ``:pull:`1756```
patch :patch:`af2cae6` ``:patch:`af2cae6```
PyPi package :pypi:`searx` ``:pypi:`searx```
manual page man :man:`bash` ``:man:`bash```
intersphinx_
--------------------------------------------------------------------------------------------------
external anchor :ref:`python:and` ``:ref:`python:and```
external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
========================== ================================== ====================================
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),
"flask": ("https://flask.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
.. _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
#. ``=`` for chapters
#. ``-`` for sections
#. ``~`` for subsections
Refer to `Sphinx Roles`_ for roles added by Sphinx.
.. _reST template:
.. admonition:: reST template
Figures & Images
================
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
.. _svg image example:
.. kernel-figure:: svg_image.svg
:alt: simple SVG image
SVG image example
.. _svg image example:
.. kernel-figure:: svg_image.svg
:alt: simple SVG image
SVG image example
DOT files (aka Graphviz)
------------------------
The kernel figure (and image) directive support **DOT** formated files, see
* 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
.. code:: reST
.. kernel-figure:: hello.dot
:alt: hello world
.. _document title:
DOT's hello world example
==============
Document title
==============
``kernel-render`` DOT
---------------------
Lorem ipsum dolor sit amet, consectetur adipisici elit ..
Further read :ref:`chapter title`.
Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
``kernel-render`` directives.
.. _chapter title:
.. code:: reST
Chapters
========
.. kernel-render:: DOT markup
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code
Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquid ex ea commodi consequat ...
digraph foo {
"bar" -> "baz";
}
Section
-------
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`).
lorem ..
.. admonition:: DOT markup
:class: rst-example
Subsection
~~~~~~~~~~
.. _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:
@ -489,3 +619,4 @@ Further list blocks
http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
.. _docutils: http://docutils.sourceforge.net/docs/index.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
zope.testrunner==4.5.1
selenium==3.141.0
linuxdoc @ git+http://github.com/return42/linuxdoc.git