DOC: re-strucuture the doc folder (#514)

* Re-organize the documentation
* Add the AiiDAlab logo
* Use pydata css
* Update readthedocs.yml
* Add strict failed when warnings
* Bump OPTIMADE-client version
* Resolve warnings in doc build

.readthedocs.yml

@@ -1,25 +1,26 @@
 ---
-# .readthedocs.yaml
-# Read the Docs configuration file
+# Read the Docs configuration file for Sphinx projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
-# Set the version of Python and other tools you might need
+# Set the OS, Python version and other tools you might need
 build:
-    os: ubuntu-20.04
+    os: ubuntu-22.04
     tools:
         python: '3.10'
 
-# Build documentation in the docs/ directory with Sphinx
+# Build documentation in the "docs/" directory with Sphinx
 sphinx:
     configuration: docs/source/conf.py
+    builder: html
+    # Let the build fail if there are any warnings
+    fail_on_warning: true
 
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
-
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
     install:
         - method: pip

aiidalab_widgets_base/bug_report.py

@@ -147,16 +147,18 @@ def install_create_github_issue_exception_handler(output, url, labels=None):
 
     Example:
     --------
-    ```python
-    output = ipw.Output()
-    install_create_github_issue_exception_handler(
-        output,
-        url='https://github.com/aiidalab/aiidalab-qe/issues/new',
-        labels=('bug', 'automated-report'))
-
-    with output:
-        display(welcome_message, app_with_work_chain_selector, footer)
-    ```
+    .. highlight:: python
+    .. code-block:: python
+
+        output = ipw.Output()
+        install_create_github_issue_exception_handler(
+            output,
+            url='https://github.com/aiidalab/aiidalab-qe/issues/new',
+            labels=('bug', 'automated-report'))
+
+        with output:
+            display(welcome_message, app_with_work_chain_selector, footer)
+
     """
     global _ORIGINAL_EXCEPTION_HANDLER
 

aiidalab_widgets_base/computational_resources.py

@@ -1224,12 +1224,8 @@ class ComputerDropdownWidget(ipw.VBox):
     """Widget to select a configured computer.
 
     Attributes:
-        value(computer UUID): Trait that points to the selected Computer instance.
-            It can be set to an AiiDA Computer UUID. It is linked to the
-            'value' trait of `self._dropdown` widget.
-        computers(Dict): Trait that contains a dictionary (label => Computer UUID) for all
-        computers found in the AiiDA database. It is linked to the 'options' trait of
-        `self._dropdown` widget.
+        value(computer UUID): Trait that points to the selected Computer instance. It can be set to an AiiDA Computer UUID. It is linked to the 'value' trait of `self._dropdown` widget.
+        computers(Dict): Trait that contains a dictionary (label => Computer UUID) for all computers found in the AiiDA database. It is linked to the 'options' trait of `self._dropdown` widget.
         allow_select_disabled(Bool):  Trait that defines whether to show disabled computers.
     """
 

docs/Makefile

@@ -1,41 +1,23 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
 BUILDDIR      = build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+.PHONY: help Makefile
 
-.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-## Runs with nitty-pick and converting warnings into errors to
-## make sure the documentation is properly written
-customdefault:
-	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
-
-all: html
-
-clean:
-	rm -r $(BUILDDIR)
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-
-view:
-	xdg-open $(BUILDDIR)/html/index.html
+rebuild:
+	@ make -s clean html

docs/source/conf.py

@@ -24,15 +24,10 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "sphinxcontrib.contentui",
     "myst_nb",
 ]
 
-jupyter_execute_notebooks = "off"
-
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.9", None),
-}
+nb_execution_mode = "off"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -92,6 +87,13 @@
 
 html_theme = "pydata_sphinx_theme"
 
+# The pydata-sphinx-theme already loads the bootstrap css.
+panels_add_bootstrap_css = False
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "_static/aiidalab_logo.png"
+
 # -- Modifications for Readthedocs ----------------------------------------
 
 

docs/source/widget-list/index.rst

@@ -12,9 +12,7 @@ See also the `corresponding git repository <https://github.com/aiidalab/aiidalab
     :glob:
 
     notebooks/aiida_datatypes_viewers
-    notebooks/codes_computers
-    notebooks/setup_computer
-    notebooks/setup_code
+    notebooks/computational_resources
     notebooks/process
     notebooks/process_list
     notebooks/structures

notebooks/computational_resources.ipynb

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cbdc6f33",
+   "metadata": {},
+   "source": [
+    "# Computational resources setup widget"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

setup.cfg

@@ -51,16 +51,15 @@ dev =
     pytest-selenium~=4.0
     selenium~=4.7.0
     webdriver-manager~=3.8
-docs =
-    MarkupSafe<2.1
-    myst-nb
-    pydata-sphinx-theme
-    sphinx
-    sphinxcontrib-contentui
-    sphinxcontrib-details-directive
 smiles =
     rdkit>=2021.09.2
     scikit-learn~=1.0.0
+docs =
+    sphinx
+    sphinx-design
+    pydata-sphinx-theme
+    myst-nb
+
 
 [flake8]
 ignore =