Add download link for examples in documentation (#7836)

This PR adds a download link to all examples in the documentation
(that are included via the examples extension). I think we should do
this, as we have text like "download the example here" at several
places already...

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index a98ffc86af87787bec4bf1ca6df2b24519989750..0647fc6e256e99f213948db533ab3ba56acc7e6c 100644 (file)
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -89,6 +89,11 @@ a:hover, a:focus {
   margin: 1px 0 0 0;
 }
 
+/* Adds a space between icon and content for fa icons */
+.icon-margin.fa::before {
+  margin-right: 0.25em;
+}
+
 #c-api-class-hierarchy code {
   font-size: 100%;
   font-weight: normal;

diff --git a/docs/ext/examples.py b/docs/ext/examples.py
index 204271f643f33280732795afd3d581ce319910c9..b9a959f5fa769753cbcc10e25ffc5a40832f7d82 100644 (file)
--- a/docs/ext/examples.py
+++ b/docs/ext/examples.py
@@ -57,6 +57,8 @@ class APIExamples(SphinxDirective):
     has_content = True
 
     logger = logging.getLogger(__name__)
+    
+    srcdir = None
 
     def run(self):
         self.state.document.settings.env.note_dependency(__file__)
@@ -88,6 +90,16 @@ class APIExamples(SphinxDirective):
             # generate tabs
             content.append(f'    .. tab:: {title}')
             content.append(f'')
+
+            if file.startswith('/'):
+                # if the file is "absolute", we can provide a download link
+                urlname = os.path.relpath(os.path.join('..', file[1:]), os.path.join(self.srcdir, '..'))
+                url = f'https://github.com/cvc5/cvc5/tree/master/{urlname}'
+                content.append(f'        .. rst-class:: fa fa-download icon-margin')
+                content.append(f'        ')
+                content.append(f'        `{urlname} <{url}>`_')
+                content.append(f'')
+
             content.append(f'        .. literalinclude:: {file}')
             content.append(f'            :language: {lang}')
             content.append(f'            :linenos:')
@@ -102,6 +114,7 @@ class APIExamples(SphinxDirective):
 
 
 def setup(app):
+    APIExamples.srcdir = app.srcdir
     app.setup_extension('sphinx_tabs.tabs')
     app.add_config_value('ex_patterns', {}, 'env')
     app.add_directive("api-examples", APIExamples)