From bee19a76f7dc8b86af3ef342acd3f4db72f51543 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 19 Dec 2019 17:05:50 +0100 Subject: [PATCH] doc: add reST primer (inital / WIP) preview: https://return42.github.io/searx/dev/reST.html includes: - :class: rst-example // admonitions with (rendered) reST markup example - extlinks to docutils Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 42 +++ docs/conf.py | 11 +- docs/dev/index.rst | 1 + docs/dev/makefile.rst | 2 +- docs/dev/reST.rst | 491 ++++++++++++++++++++++++++++ 5 files changed, 544 insertions(+), 3 deletions(-) create mode 100644 docs/dev/reST.rst diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 10f5b4ed..ee084d49 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -28,3 +28,45 @@ p.sidebar-title, .sidebar p { list-style-type: disclosure-closed; } + +/* admonitions with (rendered) reST markup examples (:class: rst-example) + * + * .. admonition:: title of the example + * :class: rst-example + * .... +/* navigation menu: use sans font and select light/dark colors for better +* contrast. +*/ + +div.rst-example { + padding-left: 12px; + padding-right: 12px; + background-color: white; + transform: scale(0.9); + transition: transform 1s; +} + +/* div.rst-example > .admonition-title { */ +/* background-color: inherit; */ +/* color: inherit; */ +/* } */ + +/* div.rst-example > .admonition-title:after{ */ +/* font-family: inherit; */ +/* font-style: italic; */ +/* content: " // hover mouse over .."; */ +/* } */ + +@media screen { + div.rst-example:hover { + transform: scale(1); + background-color: inherit; + padding-left: inherit; + padding-right: inherit; + border-left: inherit; + } + + div.rst-example:hover > .admonition-title { + display: none; + } +} diff --git a/docs/conf.py b/docs/conf.py index 9eba67cf..33954cbd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,7 @@ project = u'searx' copyright = u'2015-2019, Adam Tauber, Noémi Ványi' author = u'Adam Tauber' release, version = VERSION_STRING, VERSION_STRING +highlight_language = 'none' # General -------------------------------------------------------------- @@ -34,6 +35,12 @@ 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['duref'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') +extlinks['durole'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '') +extlinks['dudir'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '') extensions = [ 'sphinx.ext.extlinks', @@ -46,9 +53,9 @@ extensions = [ intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), - # "flask": ("https://flask.palletsprojects.com/", None), + "flask": ("https://flask.palletsprojects.com/", None), # "werkzeug": ("https://werkzeug.palletsprojects.com/", None), - # "jinja": ("https://jinja.palletsprojects.com/", None), + "jinja": ("https://jinja.palletsprojects.com/", None), } issues_github_path = "asciimoo/searx" diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 93340c1d..cb913a82 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -12,3 +12,4 @@ Developer documentation plugins translation makefile + reST diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 00825623..f5957001 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -81,7 +81,7 @@ and release a ``make pyenv``: With target ``pyenv`` a development environment (aka virtualenv) was build up in ``./local/py3/``. To make a *developer install* of searx (:origin:`setup.py`) -into this environment make target ``install`` +into this environment, use make target ``install``: .. code:: sh diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst new file mode 100644 index 00000000..c8482e77 --- /dev/null +++ b/docs/dev/reST.rst @@ -0,0 +1,491 @@ +.. _reST primer: + +=========== +reST primer +=========== + +.. sidebar:: KISS_ and readability_ + + Instead of defining more and more roles, we at searx encourage our + contributors to follow principles like KISS_ and readability_. + +We at searx are using reStructuredText (aka reST_) markup for all kind of +documentation, with the builders from the Sphinx_ project a HTML output is +generated and deployed at :docs:`github.io <.>`. + +The sources of Searx's documentation are located at :origin:`docs`. Run +:ref:`make docs-live ` to build HTML while editing. + +------ + +.. 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]`_. + +.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html + +.. sidebar:: Content matters + + The readability_ of the reST sources has its value, therefore we recommend to + make sparse usage of reST markup / .. content matters! + +**reST** is a plaintext markup language, its markup is *mostly* intuitive and +you will not need to learn much to produce well formed articles with. I use the +word *mostly*: like everything in live, reST has its advantages and +disadvantages, some markups feel a bit grumpy (especially if you are used to +other plaintext markups). + +Soft skills +=========== + +Before going any deeper into the markup let's face on some **soft skills** a +trained author brings with, to reach a well feedback from readers: + +- Documentation is dedicated to an audience and answers questions from the + audience point of view. +- Don't detail things which are general knowledge from the audience point of + view. +- Limit the subject, use cross links for any further reading. + +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. + +Admin's POV: :origin:`docs/admin` + A typical Admin knows about setting up services on a linux system, but he does + not know all the pros and cons of a searx setup. + +Developer's POV: :origin:`docs/dev` + Depending on the readability_ of code, a typical developer is able to read and + understand source code. Describe what a item aims to do (e.g. a function), + describe chronological order matters, describe it. Name the *out-of-limits + condition* and all the side effects a external developer will not know. + +.. _reST inline markup: + +Basic inline markup +=================== + +``*italics*`` -- *italics* + one asterisk for emphasis + +``**boldface**`` -- **boldface** + two asterisks for strong emphasis and + +````foo()```` -- ``foo()`` + backquotes for code samples and literals. + +``\*foo is a pointer`` -- \*foo is a pointer + If asterisks or backquotes appear in running text and could be confused with + inline markup delimiters, they have to be escaped with a backslash (``\*foo is + a pointer``). + + +Roles +===== + +A *custom interpreted text role* (:duref:`ref `) 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```. + +Docutils supports the following roles: + +* :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 + +Refer to `Sphinx Roles`_ for roles added by Sphinx. + + +Anchors & Links +=============== + +.. _reST anchor: + +Anchors +------- + +.. _ref role: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref + +To refer a point in the documentation a anchor is needed. The :ref:`reST +template ` shows an example where a chapter titled *"Chapters"* +gets an anchor named ``chapter title``. Another example from *this* document, +where the anchor named ``reST anchor``: + +.. code:: reST + + .. _reST anchor: + + Anchors + ------- + + To refer a point in the documentation a anchor is needed ... + +To refer anchors use the `ref role`_ markup: + +.. code:: reST + + Visit chapter :ref:`reST anchor`. + Or set hyperlink text manualy :ref:`foo bar `. + +.. admonition:: ``:ref:`` role + :class: rst-example + + Visist chapter :ref:`reST anchor` + Or set hyperlink text manualy :ref:`foo bar `. + +.. _reST ordinary ref: + +link ordinary URL +----------------- + +If you need to reference external URLs use *named* hyperlinks to maintain +readability of reST sources. Here is a example taken from *this* article: + +.. code:: reST + + .. _Sphinx Field Lists: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html + + With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more + readable. + + And this shows the alternative (less readable) hyperlink markup `Sphinx Field + Lists + `__. + +.. admonition:: Named hyperlink + :class: rst-example + + With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more + readable. + + And this shows the alternative (less readable) hyperlink markup `Sphinx Field + Lists + `__. + + +.. _reST smart ref: + +smart references +---------------- + +With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external +content becomes smart. To refer ... + +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 + + +Intersphinx is configured in :origin:`docs/conf.py`: + +.. code:: python + + intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "flask": ("https://flask.palletsprojects.com/", None), + "jinja": ("https://jinja.palletsprojects.com/", None), + } + + +To list all anchors of the inventory (e.g. ``python``) use: + +.. code:: sh + + $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv + + +.. _reST basic structure: + +Basic article structure +======================= + +The basic structure of an article makes use of heading adornments to markup +chapter, sections and subsections. + +#. ``=`` with overline for document title +#. ``=`` for chapters +#. ``-`` for sections +#. ``~`` for subsections + +.. _reST template: + +.. 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 .. + +.. _reST lists: + +List markups +============ + +Bullet list +----------- + +List markup (:duref:`ref `) is simple: + +.. code:: reST + + - This is a bulleted list. + + 1. Nested lists are possible, but be aware that they must be separated from + the parent list items by blank line + 2. Second item of nested list + + - It has two items, the second + item uses two lines. + + #. This is a numbered list. + #. It has two items too. + +.. admonition:: bullet list + :class: rst-example + + - This is a bulleted list. + + 1. Nested lists are possible, but be aware that they must be separated from + the parent list items by blank line + 2. Second item of nested list + + - It has two items, the second + item uses two lines. + + #. This is a numbered list. + #. It has two items too. + + +Definition list +--------------- + +.. sidebar:: definition term + + Note that the term cannot have more than one line of text. + +Definition lists (:duref:`ref `) are created as follows: + +.. code:: reST + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + +.. admonition:: definition list + :class: rst-example + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + + +Quoted paragraphs +----------------- + +Quoted paragraphs (:duref:`ref `) are created by just indenting +them more than the surrounding paragraphs. Line blocks (:duref:`ref +`) are a way of preserving line breaks: + +.. code:: reST + + normal paragraph ... + lorem ipsum. + + Quoted paragraph ... + lorem ipsum. + + | These lines are + | broken exactly like in + | the source file. + + +.. admonition:: Quoted paragraph and line block + :class: rst-example + + normal paragraph ... + lorem ipsum. + + Quoted paragraph ... + lorem ipsum. + + | These lines are + | broken exactly like in + | the source file. + + +.. _reST field list: + +Field Lists +----------- + +.. _Sphinx Field Lists: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html + +.. sidebar:: bibliographic fields + + First lines fields are bibliographic fields, see `Sphinx Field Lists`_. + +Field lists are used as part of an extension syntax, such as options for +directives, or database-like records meant for further processing. Field lists +are mappings from field names to field bodies. They marked up like this: + +.. code:: reST + + :fieldname: Field content + :foo: first paragraph in field foo + + second paragraph in field foo + + :bar: Field content + +.. admonition:: Field List + :class: rst-example + + :fieldname: Field content + :foo: first paragraph in field foo + + second paragraph in field foo + + :bar: Field content + + +They are commonly used in Python documentation: + +.. code:: python + + def my_function(my_arg, my_other_arg): + """A function just for me. + + :param my_arg: The first of my arguments. + :param my_other_arg: The second of my arguments. + + :returns: A message (just for me, of course). + """ + +Further list blocks +------------------- + +- field lists (:duref:`ref `, with caveats noted in + :ref:`reST field list`) +- option lists (:duref:`ref `) +- quoted literal blocks (:duref:`ref `) +- doctest blocks (:duref:`ref `) + + +.. _KISS: https://en.wikipedia.org/wiki/KISS_principle +.. _readability: https://docs.python-guide.org/writing/style/ +.. _Sphinx-Primer: + http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _reST: https://docutils.sourceforge.io/rst.html +.. _Sphinx Roles: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html +.. _Sphinx: http://www.sphinx-doc.org +.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html +.. _Sphinx markup constructs: + http://www.sphinx-doc.org/en/stable/markup/index.html +.. _`sphinx cross references`: + http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations +.. _sphinx.ext.extlinks: + https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html +.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html +.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html +.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html +.. _Sphinx's Python domain: + http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain +.. _Sphinx's C domain: + http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs +.. _doctree: + 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