From b1912607ae9783d6ccf648bd7706a64eca5bedb9 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 12 Mar 2022 10:18:08 +0100 Subject: [mod] replace /help by /info pages and include pages in project docs This patch implements a bolierplate to share content from info-pages of the SearXNG instance (URL /info) with the project documentation (path /docs/user). The info pages are using Markdown (CommonMark), to include them in the project documentation (reST) the myst-parser [1] is used in the Sphinx-doc build chain. If base_url is known (defined in settings.yml) links to the instance are also inserted into the project documentation:: searxng_extra/docs_prebuild [1] https://www.sphinx-doc.org/en/master/usage/markdown.html Signed-off-by: Markus Heiser --- docs/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 2f58bdb12..89d6bb8f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,7 +35,7 @@ master_doc = "index" source_suffix = '.rst' numfig = True -exclude_patterns = ['build-templates/*.rst'] +exclude_patterns = ['build-templates/*.rst', 'user/*.md'] import searx.engines import searx.plugins @@ -94,7 +94,6 @@ extlinks['pull-searx'] = ('https://github.com/searx/searx/pull/%s', 'PR ') # links to custom brand extlinks['origin'] = (GIT_URL + '/blob/' + GIT_BRANCH + '/%s', 'git://') extlinks['patch'] = (GIT_URL + '/commit/%s', '#') -extlinks['search'] = (SEARXNG_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', '') @@ -123,8 +122,11 @@ extensions = [ 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling. "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs + 'myst_parser', # https://www.sphinx-doc.org/en/master/usage/markdown.html ] +suppress_warnings = ['myst.domains'] + intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "flask": ("https://flask.palletsprojects.com/", None), -- cgit v1.2.3 From 8751940169378d89a3151df57a40d6ada21f035c Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 12 Mar 2022 10:54:30 +0100 Subject: [interim fix] of sphinx-tabs and sphinx-jinja The myst-parser requires >= docutils v.0.17 what ends in a dependency hell where plugins sphinx-tabs and sphinx-jinja we use are involved. This patch can be reverted when [2], [3], [4] are solved and new release is available / see [1]. [1] https://github.com/searxng/searxng/pull/954 [2] https://github.com/executablebooks/sphinx-tabs/issues/152 [3] https://github.com/executablebooks/sphinx-tabs/pull/153 [4] https://github.com/executablebooks/sphinx-tabs/pull/154 Signed-off-by: Markus Heiser --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 89d6bb8f6..1dd5693ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,7 +116,7 @@ extensions = [ "sphinx.ext.intersphinx", "pallets_sphinx_themes", "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst - "sphinxcontrib.jinja", # https://github.com/tardyp/sphinx-jinja + "sphinx_jinja", # https://github.com/tardyp/sphinx-jinja "sphinxcontrib.programoutput", # https://github.com/NextThought/sphinxcontrib-programoutput 'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive. 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. -- cgit v1.2.3