Update docs to remove all build warnings

All warnings have been removed by:
- Move `!pip install` statements to a separate cell in all notebooks,
  making the cell "shellscript" code and add a sentence immediately
  before stating the same thing.
- Add all files to a Sphinx `toctree` tag, specifically extending the
  header nav with the "More" dropdown, which includes "contribute",
  "tools", and "resources".
- Find online and add the image for the Protégé configuration.

Update the configuration to remove the primary sidebar from pages that
have no section navigation.

Since no warnings are produced (locally) now, the CI workflow has been
updated to include the `-W` flag for sphinx-build, which treats warnings
as errors during the build.

.github/workflows/doc.yml

@@ -44,6 +44,10 @@ jobs:
     - name: Build HTML
       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