Updated docs to use jinja template for component doc links

Author: philipstarkey

docs/source/_templates/components.rst

@@ -0,0 +1,47 @@
+{% if current_project != 'the labscript suite' %}
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    The labscript suite <{{intersphinx_mapping['labscript-suite'][0]}}>
+
+{% endif %}
+*labscript suite* components
+============================
+
+The *labscript suite* is modular by design, and is comprised of:
+
+.. list-table:: Python libraries
+    :widths: 10 90
+    :header-rows: 0
+
+    {% for prog, item in programs.items() if item.type == 'lib' %}
+    * - .. image:: {{item.img}}
+             :target: {{intersphinx_mapping['%s' | format(prog)][0]}}
+             :class: labscript-suite-icon
+      - |{{prog}}|_ --- {{item.desc}}
+    {% endfor %}
+
+.. list-table:: Graphical applications
+    :widths: 10 90
+    :header-rows: 0
+
+    {% for prog, item in programs.items() if item.type == 'gui' %}
+    * - .. image:: {{item.img}}
+             :target: {{intersphinx_mapping['%s' | format(prog)][0]}}
+             :class: labscript-suite-icon
+      - |{{prog}}|_ --- {{item.desc}}
+    {% endfor %}
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    {% for prog in programs|sort if prog != current_project %}
+    {{prog}} <{{intersphinx_mapping['%s' | format(prog)][0]}}>
+    {% endfor %}
+
+{% for prog in programs %}
+.. |{{prog}}| replace:: **{{prog}}**
+.. _{{prog}}: {{intersphinx_mapping['%s' | format(prog)][0]}}
+{% endfor %}

docs/source/conf.py

@@ -14,6 +14,7 @@
 from pathlib import Path
 from m2r import MdInclude
 from recommonmark.transform import AutoStructify
+from jinja2 import FileSystemLoader, Environment
 
 # -- Project information (unique to each project) -------------------------------------
 
@@ -187,59 +188,6 @@
 # Customize the html_theme
 html_theme_options = {'navigation_depth': 3}
 
-# Template for generating the components.rst file
-# fmt:off
-components_rst_template = \
-"""
-{metapackage_toctree}
-
-*labscript suite* components
-============================
-
-The *labscript suite* is modular by design, and is comprised of:
-
-.. list-table:: Python libraries
-    :widths: 10 90
-    :header-rows: 0
-
-{lib}
-
-.. list-table:: Graphical applications
-    :widths: 10 90
-    :header-rows: 0
-
-{gui}
-
-.. toctree::
-    :maxdepth: 2
-    :hidden:
-
-{toctree_entires}
-
-{rst_defs}
-"""
-
-components_rst_table_template = \
-"""    * - .. image:: {img}
-             :target: {target}
-             :class: labscript-suite-icon
-      - |{prog}|_ --- {desc}
-"""
-
-components_rst_link_template = \
-""".. |{prog}| replace:: **{prog}**
-.. _{prog}: {target}
-"""
-
-components_rst_metapackage_template = \
-""".. toctree::
-    :maxdepth: 2
-    :hidden:
-
-    Metapackage documentation <{}>
-"""
-# fmt:on
-
 # Use m2r only for mdinclude and recommonmark for everything else
 # https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
 def setup(app):
@@ -261,43 +209,14 @@ def setup(app):
 
     # generate the components.rst file dynamically so it points to stable/latest
     # of subprojects correctly
-    components_rst_table = {
-        "lib": "",
-        "gui": "",
-    }
-    components_rst_link = ""
-    components_rst_toctree = ""
-    components_rst_metapackage = ""
-    if project != 'the labscript suite':
-        components_rst_metapackage = components_rst_metapackage_template.format(
-            intersphinx_mapping['labscript-suite'][0]
-        )
-    metapackage_img = img_path + "/labscript-suite-rectangular-transparent_138nx70n.svg"
-    for ls_prog, data in labscript_suite_programs.items():
-        components_rst_table[data['type']] += components_rst_table_template.format(
-            prog=ls_prog,
-            labscript_suite_doc_version=labscript_suite_doc_version,
-            target=intersphinx_mapping[ls_prog][0],
-            **data
-        )
-        components_rst_link += components_rst_link_template.format(
-            prog=ls_prog,
-            labscript_suite_doc_version=labscript_suite_doc_version,
-            target=intersphinx_mapping[ls_prog][0],
-        )
-    for ls_prog in sorted(labscript_suite_programs):
-        if ls_prog != project:
-            components_rst_toctree += "    {} <{}>\n".format(
-                ls_prog, intersphinx_mapping[ls_prog][0]
-            )
-
-    components_rst = components_rst_template.format(
-        toctree_entires=components_rst_toctree,
-        rst_defs=components_rst_link,
-        labscript_suite_doc_version=labscript_suite_doc_version,
-        metapackage_toctree=components_rst_metapackage,
-        **components_rst_table
-    )
-
+    loader = FileSystemLoader(Path(__file__).resolve().parent / templates_path[0])
+    env = Environment(loader=loader)
+    template = env.get_template('components.rst')
     with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f:
-        f.write(components_rst)
+        f.write(
+            template.render(
+                intersphinx_mapping=intersphinx_mapping,
+                programs=labscript_suite_programs,
+                current_project=project,
+            )
+        )

docs/source/index.rst

@@ -11,9 +11,24 @@ This documentation is primarily for developers who might want to use this common
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
    api_reference/index
+   
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: FURTHER DOCUMENTATION
+
    components
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: LINKS
+
    Home Page <http://labscriptsuite.org>
-   Source Code <https://github.com/labscript-suite/labscript-suite>
+   Source Code <https://github.com/labscript-suite/labscript-utils>
    BitBucket Archive <http://bitbucket-archive.labscriptsuite.org/#!/labscript_suite/labscript_utils>
+
+.. todolist::