Update for Furo (#39)

docs/source/_templates/page.html

@@ -0,0 +1,43 @@
+{#
+
+See https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/page.html for the original
+block this is overwriting.
+
+The part that is customized is between the "begin of custom part" and "end of custom part"
+comments below. It uses the same styles as the existing right sidebar code.
+
+#}
+{% extends "furo/page.html" %}
+{% block right_sidebar %}
+<div class="toc-sticky toc-scroll">
+    {# begin of custom part #}
+    <div class="toc-title-container">
+    <span class="toc-title">
+        YosysHQ
+    </span>
+    </div>
+    <div class="toc-tree-container yosyshq-links" style="padding-bottom: 0">
+    <div class="toc-tree">
+        <ul>
+        <li></li>
+        <li><a class="reference external" href="https://yosyshq.readthedocs.io">Docs</a></li>
+        <li><a class="reference external" href="https://blog.yosyshq.com">Blog</a></li>
+        <li><a class="reference external" href="https://www.yosyshq.com">Website</a></li>
+        </ul>
+    </div>
+    </div>
+    {# end of custom part #}
+    {% if not furo_hide_toc %}
+    <div class="toc-title-container">
+    <span class="toc-title">
+        {{ _("On this page") }}
+    </span>
+    </div>
+    <div class="toc-tree-container">
+    <div class="toc-tree">
+        {{ toc }}
+    </div>
+    </div>
+    {% endif %}
+</div>
+{% endblock %}

docs/source/conf.py

@@ -3,26 +3,40 @@
 author = 'YosysHQ GmbH'
 copyright ='2021 YosysHQ GmbH'
 
+templates_path = ['_templates']
+
 # select HTML theme
-html_theme = 'press'
-html_logo = '../static/logo.png'
-html_favicon = '../static/favico.png'
-html_css_files = ['yosyshq.css', 'custom.css']
-html_sidebars = {'**': ['util/searchbox.html', 'util/sidetoc.html']}
+html_theme = "furo"
 
 # These folders are copied to the documentation's HTML output
-html_static_path = ['../static', "../images"]
+html_static_path = ['../static', '../images']
+
+html_logo = '../static/logo.png'
+html_favicon = '../static/favico.png'
+html_css_files = ['custom.css']
 
 # code blocks style 
 pygments_style = 'colorful'
 highlight_language = 'systemverilog'
 
 html_theme_options = {
-    'external_links' : [
-        ('YosysHQ Docs', 'https://yosyshq.readthedocs.io'),
-        ('Blog', 'https://blog.yosyshq.com'),
-        ('Website', 'https://www.yosyshq.com'),
-    ],
+    "sidebar_hide_name": True,
+
+    "light_css_variables": {
+        "color-brand-primary": "#d6368f",
+        "color-brand-content": "#4b72b8",
+        "color-api-name": "#8857a3",
+        "color-api-pre-name": "#4b72b8",
+        "color-link": "#8857a3",
+    },
+
+    "dark_css_variables": {
+        "color-brand-primary": "#e488bb",
+        "color-brand-content": "#98bdff",
+        "color-api-name": "#8857a3",
+        "color-api-pre-name": "#4b72b8",
+        "color-link": "#be95d5",
+    },
 }
 
 extensions = ['sphinx.ext.autosectionlabel']

docs/source/eqsetup.rst

@@ -161,8 +161,8 @@ Then you can use this to run the equivalence check with SBY:
 	ln -s ../../test_eq.sv ../../test_eq.sby .
 	sby -f test_eq.sby
 
-Reporting the result
-~~~~~~~~~~~~~~~~~~~~
+Reporting equivalence
+~~~~~~~~~~~~~~~~~~~~~
 
 Finally, write the result of the equivalence check to the file ``output.txt``, preceded by ``1``:
 

docs/source/mutate.rst

@@ -55,51 +55,51 @@ The yosys script (``mutate.ys`` in this example) that you need to generate shoul
 
 - Read the intermediary file containing the elaborated design:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		echo "read_verilog ../../database/design.il" > mutate.ys
+    echo "read_verilog ../../database/design.il" > mutate.ys
 
 - Apply the mutate command(s) found in ``input.txt``.
 
-	If there is only one mutation, and you do not wish to create a ``mutsel`` input, enter the command as-is, just remove the leading ``1``, e.g. like this:
+  If there is only one mutation, and you do not wish to create a ``mutsel`` input, enter the command as-is, just remove the leading ``1``, e.g. like this:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		cut -f2- -d' ' input.txt >> mutate.ys
+    cut -f2- -d' ' input.txt >> mutate.ys
 
-	If you do wish to add a ``mutsel`` input to the design, you need to add the ``-ctrl`` parameter to the ``mutate`` command's arguments:
+  If you do wish to add a ``mutsel`` input to the design, you need to add the ``-ctrl`` parameter to the ``mutate`` command's arguments:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		while read -r idx mut; do
-			echo "mutate -ctrl mutsel 8 ${idx} ${mut#* }" >> mutate.ys
-		done < input.txt
+    while read -r idx mut; do
+      echo "mutate -ctrl mutsel 8 ${idx} ${mut#* }" >> mutate.ys
+    done < input.txt
 
-	This code snippet works for one or many mutations in ``input.txt`` thanks to the ``while`` loop. If there are multiple mutations to be applied, it will add all the mutate commands to the script. Always make sure to add the control input when there are multiple mutations!
+  This code snippet works for one or many mutations in ``input.txt`` thanks to the ``while`` loop. If there are multiple mutations to be applied, it will add all the mutate commands to the script. Always make sure to add the control input when there are multiple mutations!
 
 - Optionally, add any other yosys commands you wish to use to transform the design to work with your testbench. For example, if you want to run the design on hardware, you may synthesize it here:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		echo "synth_ice40 -top top_module" >> mutate.ys
+    echo "synth_ice40 -top top_module" >> mutate.ys
 
-	You can also change the name of the module if needed:
+  You can also change the name of the module if needed:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		echo "rename top_module mutated" >> mutate.ys
+    echo "rename top_module mutated" >> mutate.ys
 
 - Finally, export the design to a format that can be used by your testbench. In the example of the hardware test, this might be json:
 
-	.. code-block:: text
+  .. code-block:: text
 
-		echo "write_json mutated.json" >> mutate.ys
+    echo "write_json mutated.json" >> mutate.ys
 
 After generating the script, execute it with yosys:
 
-	.. code-block:: text
+.. code-block:: text
 
-		yosys -ql mutate.log mutate.ys
+  yosys -ql mutate.log mutate.ys
 
 The Yosys ``mutate`` command
 ----------------------------

docs/source/requirements.txt

@@ -1 +1 @@
-sphinx-press-theme
+furo

docs/static/custom.css

@@ -1 +1,18 @@
-/* empty */
+/* Don't hide the right sidebar as we're placing our fixed links there */
+aside.no-toc {
+    display: block !important;
+}
+
+/* Colorful headings */
+h1 {
+    color: var(--color-brand-primary);
+}
+
+h2, h3, h4, h5, h6 {
+    color: var(--color-brand-content);
+}
+
+/* Use a different color for external links */
+a.external {
+    color: var(--color-brand-primary) !important;
+}