working dictionary link

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 <hello>` in the src files
+# enables syntax like
-
+" :source:`v1.1_010/firefox/00-proxy.yml` "
-extlinks = {'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/%s',
+extlinks = {'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/%s',
-                       'source: %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')

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]
 

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
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_001/firefox/00-proxy.yml
-
-    ---
-    version: 1.1
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
    :linenos:
    :language: yaml
-   :caption: titi
+   :caption: An empty rougail dictionnary file. It's a YAML format.
-
+   :name: RougailDictionaryEmptyFile
-:source:`v1.1_001/firefox/00-proxy.yml`
 
 :download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml>`
 

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 <RougailDictionaryEmptyFile>`