From 53e274229b774bd1adfafbf785b81c51c1cab2d4 Mon Sep 17 00:00:00 2001
From: Gereon Kremer <gkremer@stanford.edu>
Date: Mon, 3 Jan 2022 13:25:00 -0800
Subject: [PATCH] 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...
---
 docs/_static/custom.css |  5 +++++
 docs/ext/examples.py    | 13 +++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index a98ffc86a..0647fc6e2 100644
--- 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 204271f64..b9a959f5f 100644
--- 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)
-- 
2.30.2