Build docs better in CI/CD

.github/workflows/doc.yml

@@ -30,18 +30,24 @@ jobs:
 
     - name: Install dependencies
       run: |
+        # System dependencies
+        sudo apt-get update && sudo apt-get install -y pandoc
+
+        # Python dependencies
         python -m pip install --upgrade pip
         pip install -U setuptools wheel
-        pip install -r requirements_docs.txt
+        pip install -r requirements_docs.txt -r sphinx/requirements.txt
 
     - name: Render documentation from ttl
       run: python sphinx/ttl_to_rst.py
 
     - name: Build HTML
-      uses: ammaraskar/sphinx-action@master
-      with:
-        docs-folder: "sphinx/"
-        pre-build-command: "apt-get update -y; apt-get install -y pandoc"
+      run: make html
+      working-directory: sphinx
+      env:
+        # -v: Verbose
+        # -W: Turn warnings into errors
+        SPHINXOPTS: "-v -W"
 
     # Still upload built documentation as an artifact if not deploying
     # This is to provide the opportunity to download the built documentation

sphinx/about.rst

@@ -1,5 +1,5 @@
 About the Battery Interface Ontology
-==========================
+====================================
 
 The Battery Interface Ontology (BattINFO) is a semantic resource for the terms and relations needed to describe things, processes, and data in the battery domain. It can be used to **generate linked data** for the Semantic Web, **comply with the FAIR data guidelines**, support **interoperaility of data** among different systems, and more!
 

sphinx/conf.py

@@ -120,6 +120,8 @@
 
 html_theme_options = {
   # "show_nav_level": 4
+  "header_links_before_dropdown": 5, # show 5 links before "More" dropdown
+  "primary_sidebar_end": [],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -161,7 +163,14 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    "**": ["sidebar-nav-bs"],
+    "about": [],
+    "battinfo": [],
+    "contribute": [],
+    "faq": [],
+    "getstarted": [],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -299,4 +308,10 @@
 
 # MatAttributeDocumenter.add_directive_header = _add_directive_header
 
+suppress_warnings = [
+    # Suppress "duplicate label" warnings in `battinfo.rst`.
+    #   These are due to similarly named (prefLabel) concepts in the ontology,
+    #   as the prefLabel is used as the section title.
+    "autosectionlabel.battinfo",
+  ]
 

sphinx/contribute.rst

@@ -24,15 +24,15 @@ We recommend using the `forking
 workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow>`__
 to contribute additions/deletions. Fork this repository, clone the fork
 on your local PC, create your branch based on the existing ``dev``
-branch (e.g. ``dev_john_doe``) and work on the editions in you local
+branch (e.g. ``dev_john_doe``) and work on the editions in you local
 copy.
 
 You can edit ontologes in two main ways. One is programmatically, using
 for instance `EMMOntoPy <https://github.com/emmo-repo/EMMOntoPy>`__. The
 second and more common is using the interface provided by the Protégé
 software. In case of the latter, `install
 Protégé <https://protege.stanford.edu/>`__ and use it to open the
-ontology file you wish to edit. Before adding elements, ensure Prot´égé
+ontology file you wish to edit. Before adding elements, ensure Protégé
 is configured to create IRIs in the right format:
 
 -  Open Protégé
@@ -49,5 +49,5 @@ is configured to create IRIs in the right format:
    request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`__.
 -  We will merge the request after assessing it.
 
-.. |Protege config.| image:: doc/img/protege_config_contribute.png
+.. |Protege config.| image:: img/protege_config_contribute.png