exticlude directive

docs/conf.py

@@ -49,9 +49,9 @@ extensions = [
 #uses the xref.py extension
 xref_links = {"link_name" : ("user text", "url")}
 
-link_name = "Sphinx External Links"
+#link_name = "Sphinx External Links"
-user_text = "modified External Links Extension"
+#user_text = "modified External Links Extension"
-url = "http://www.sphinx-doc.org/en/stable/ext/extlinks.html"
+#url = "http://www.sphinx-doc.org/en/stable/ext/extlinks.html"
 
 links = {
         'tiramisu': ('Tiramisu', 'https://tiramisu.readthedocs.io/en/latest/'),

docs/ext/extinclude.py

@@ -5,25 +5,58 @@ from docutils import nodes
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.typing import ExtensionMetadata
+from sphinx.directives.code import LiteralInclude, container_wrapper
 
 from httpx import get
 
-class HelloDirective(SphinxDirective):
+class ExtInclude(LiteralInclude):
-    """A directive to say hello!"""
+    """A directive to include code that comes from an url
 
-    required_arguments = 1
+    Sample use::
 
+        .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
+           :linenos:
+           :language: yaml
+           :caption: this is a interesting code
+
+    - parameter required
+    - linenos, language and caption are optionnal.
+
+    :default language: yaml
+    :default caption: extinclude parameter (url)
+
+    """
 
     def run(self) -> list[nodes.Node]:
-        content = get("https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_001/firefox/00-proxy.yml")
+        url = self.arguments[0]
+        content = get(url)
         #paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!')
-        paragraph_node = nodes.paragraph(text=content.text)
+        code = content.text
-        return [paragraph_node]
+        literal = nodes.literal_block(code, code)
+        if 'language' in self.options:
+            literal['language'] = self.options['language']
+        else:
+            literal['language'] = 'yaml'
+        literal['linenos'] = 'linenos' in self.options
+        if 'caption' in self.options:
+            caption = self.options.get('caption')
+        else:
+            caption = url
+        literal['caption'] = caption
+        # FIXME handle the `name` option too
+
+        literal = container_wrapper(self, literal, caption)
+
+        self.add_name(literal)
+        return [literal]
+
+        #paragraph_node = nodes.paragraph(text=content.text)
+        #return [paragraph_node]
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
 
-    app.add_directive('hello', HelloDirective)
+    app.add_directive('extinclude', ExtInclude)
 
     return {
         'version': '0.1',

docs/gettingstarted.rst

@@ -76,10 +76,15 @@ Here is an empty rougail dictionary YAML file
     ---
     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
+
 :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>`
 
-.. hello:: world
 
 Here is a :term:`dictionary` example:
 

docs/readme.txt

@@ -14,6 +14,8 @@ Then install the sphinx libraries::
     ./.venv/bin/pip3 install sphinx
     ./.venv/bin/pip3 install sphinx_rtd_theme
     ./.venv/bin/pip3 install sphinx_lesson
+    ./.venv/bin/pip3 install httpx
+
 
 The generatef html output is located in the `docs/build/html` subfolder,
 you can modify the target or the output type in the :file:`docs/Makefile`.