From e1566e68aa9e18e60a86d0eea8772a3673cb3c7b Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 19 Dec 2019 23:36:53 +0100 Subject: [PATCH] doc: add content to reST primer (WIP) // linuxdoc Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 8 + docs/conf.py | 11 + docs/dev/hello.dot | 3 + docs/dev/reST.rst | 311 ++++++++++++++++++++-------- docs/dev/svg_image.svg | 10 + requirements-dev.txt | 1 + 6 files changed, 254 insertions(+), 90 deletions(-) create mode 100644 docs/dev/hello.dot create mode 100644 docs/dev/svg_image.svg diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index ee084d499..747cb0507 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -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 diff --git a/docs/conf.py b/docs/conf.py index 33954cbd2..b960621d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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" diff --git a/docs/dev/hello.dot b/docs/dev/hello.dot new file mode 100644 index 000000000..504621dfc --- /dev/null +++ b/docs/dev/hello.dot @@ -0,0 +1,3 @@ +graph G { + Hello -- World +} diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index c8482e77d..5522f9e15 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -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 `) 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 `) 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 ` ``:download:`this file ``` +: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 + + + + + + + +.. admonition:: SVG markup + :class: rst-example + + .. _hello_svg_render: + + .. kernel-render:: SVG + :caption: Embedded **SVG** markup + :alt: so-nw-arrow + + + + + + - 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 diff --git a/docs/dev/svg_image.svg b/docs/dev/svg_image.svg new file mode 100644 index 000000000..5405f85b8 --- /dev/null +++ b/docs/dev/svg_image.svg @@ -0,0 +1,10 @@ + + + + + + + + diff --git a/requirements-dev.txt b/requirements-dev.txt index 0bdf20469..54643908e 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -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