From d47011efe4f198f6eba2c0d9808a02347cf31d76 Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 15 Oct 2024 07:31:31 +0200 Subject: [PATCH] working dictionary link --- docs/conf.py | 81 +++++++---------------------------- docs/ext/extinclude.py | 8 ++-- docs/gettingstarted.rst | 15 ++----- docs/tutorial/preliminary.rst | 2 +- 4 files changed, 24 insertions(+), 82 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index dd3546ca7..bbf4d8f24 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,28 +1,20 @@ # Configuration file for the Sphinx documentation builder. # -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - # -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# - import sys, os # sys.path.insert(0, os.path.abspath('.')) #sys.path.append(os.path.abspath('ext')) sys.path.append('.') +#---- debug mode ---- # shows/hides the todos todo_include_todos = False # -- Project information ----------------------------------------------------- project = 'Rougail' -copyright = '2019-2023, Silique' +copyright = '2019-2024, Silique' author = 'gwen' # The short X.Y version @@ -37,52 +29,44 @@ release = '1.0' # # needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. - extensions = [ 'sphinx.ext.extlinks', 'sphinx_lesson', 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'ext.xref', 'ext.extinclude' ] -#uses the xref.py extension +#---- xref links ---- +#import the xref.py extension xref_links = {"link_name" : ("user text", "url")} #link_name = "Sphinx External Links" #user_text = "modified External Links Extension" #url = "http://www.sphinx-doc.org/en/stable/ext/extlinks.html" - +#enables syntax like: +" :xref:`tiramisu` " links = { 'tiramisu': ('Tiramisu', 'https://tiramisu.readthedocs.io/en/latest/'), 'tiramisu library': ('Tiramisu library homepage', 'https://forge.cloud.silique.fr/stove/tiramisu'), } - xref_links.update(links) - +#---- ext links ---- # **extlinks** 'sphinx.ext.extlinks', -# enables syntax like :proxy:`my source ` in the src files - -extlinks = {'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/%s', - 'source: %s')} - +# enables syntax like +" :source:`v1.1_010/firefox/00-proxy.yml` " +extlinks = {'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/%s', + 'source: %s'), + } +#---- options for HTML output ---- default_role = "code" - html_theme = "sphinx_rtd_theme" - pygments_style = 'sphinx' - html_short_title = "Rougail" html_title = "Rougail documenation" - -# If true, links to the reST sources are added to the pages. html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. html_show_copyright = True +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None +html_static_path = ['_static'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -112,39 +96,6 @@ language = 'en' # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['.venv', 'build', '_build', 'Thumbs.db', '.DS_Store'] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -#html_theme = 'alabaster' -# **themes** -#html_theme = 'bizstyle' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} def setup(app): app.add_css_file('css/custom.css') diff --git a/docs/ext/extinclude.py b/docs/ext/extinclude.py index 6ebc27cb1..1daa770c3 100644 --- a/docs/ext/extinclude.py +++ b/docs/ext/extinclude.py @@ -32,6 +32,7 @@ class ExtInclude(LiteralInclude): content = get(url) #paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!') code = content.text + literal = nodes.literal_block(code, code) if 'language' in self.options: literal['language'] = self.options['language'] @@ -43,13 +44,12 @@ class ExtInclude(LiteralInclude): else: caption = url literal['caption'] = caption - # FIXME handle the `name` option too - + if 'name' in self.options: + literal['name'] = self.options.get('name') literal = container_wrapper(self, literal, caption) - self.add_name(literal) - return [literal] + return [literal] #paragraph_node = nodes.paragraph(text=content.text) #return [paragraph_node] diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index f6b0a613f..e32954c7d 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -66,22 +66,13 @@ Before getting started with Rougail we need to learn the specifics of the YAML d .. todo:: parler de jinja https://jinja.palletsprojects.com - -.. _empty_dictionary: - Here is an empty rougail dictionary YAML file -.. code-block:: yaml - - --- - version: 1.1 - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_001/firefox/00-proxy.yml :linenos: :language: yaml - :caption: titi - -:source:`v1.1_001/firefox/00-proxy.yml` + :caption: An empty rougail dictionnary file. It's a YAML format. + :name: RougailDictionaryEmptyFile :download:`source file ` diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 2a2220965..d45d96688 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -9,4 +9,4 @@ Preliminaries - use a rougail format version - use the rougail command line - +- :ref:`Here is an empty rougail dictionnary `