Docs: switch to sphinx-book-theme from pydata_sphinx_theme

The main reason for the switch is to have access to theme-specific elements like
margin notes. Another major change compared to `pydata_sphinx_theme` is the
absence of a top-level header, which has us move the contents overview into the
sidebar. This has the advantage that the user immediately has a bird's eye
glance of the documentation contents. Until the documentation becomes larger,
this approach is preferable.

Several changes are made to the sidebar:

1. Override the default `icon-links.html` component to include an AiiDA icon
   that links to the AiiDA website.
2. Override the `sbt-sidebar-nav.thml` component to adapt the default maxdepth.
3. A logo is added for dark mode.

Some other additions and tweaks:

1. Added badged to the landing page instead of the release version.
2. Adapt the sidebar `toctree` to include captions and point directly to some
   subsections.
3. The Python API now has a `toctree` element with a clear name, and the
   `maxdepth` is adapted to make it more readable.
4. Several panels on the landing page are removed, since the corresponding
   top-level sections are no longer part of the `toctree`. This also makes the
   remaining panels to the `Get started` and tutorial sections more prominent.

Finally, the `intersphinx_mapping` to the `aiida-core` docs is fixed, along with
several broken references, mostly in the Hubbard docstring.

The `pydantic` and `typing` related intersphinx warnings are ignored using
`nitpick_ignore_regex`, since pydantic doesn't use `sphinx` and there seem to
be issues with referencing `typing` classes.

.gitignore

@@ -111,4 +111,4 @@ ENV/
 submit_test/
 
 # Autogenerated API docs
-docs/source/reference/api/aiida_quantumespresso
+docs/source/reference/api/auto

docs/Makefile

@@ -24,7 +24,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 customdefault:
 	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
-all: html view
+all: clean html view
 
 clean:
 	rm -rf $(BUILDDIR)
@@ -34,6 +34,5 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-
 view:
 	open $(BUILDDIR)/html/index.html

docs/source/_static/aiida-qe-custom.css

@@ -11,18 +11,29 @@
     font-size: 140%;
 }
 
-div.navbar-brand-box a.navbar-brand img {
-    display: block;
-    height: auto;
-    width: auto;
-    max-height: 100vh;
-    max-width: 90%;
-    margin: 0 auto;
-    padding-left: 30px
+.navbar-brand {
+    padding: 0;
+    padding-top: 0.5rem;
+}
+
+img.logo__image {
+    max-height: 180px;
+    padding-left: 1.5rem;
+    padding-bottom: 1rem;
+}
+
+.navbar-icon-links i.fa-brands {
+    font-size: 40px!important;
+}
+
+img.aiida-logo {
+    height: 40px!important;
+}
+
+.fa {
+    color: var(--pst-color-primary);
 }
 
-@media (min-width: 768px) {
-    div.navbar-brand-box a.navbar-brand img {
-        max-height: 100vh !important
-    }
+.bd-search {
+    padding: 0 1rem;
 }

docs/source/_templates/icon-links.html

@@ -0,0 +1,40 @@
+{%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%}
+  {%- if url | length > 2 %}
+        <li class="nav-item">
+          {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link", "rel": "noopener", "target": "_blank", "data-bs-toggle": "tooltip", "data-bs-placement": "bottom"} %}
+          {%- if attributes %}{% for key, val in attributes.items() %}
+            {% set _ = attributesDefault.update(attributes) %}
+          {% endfor %}{% endif -%}
+          {% set attributeString = [] %}
+          {% for key, val in attributesDefault.items() %}
+            {%- set _ = attributeString.append('%s="%s"' % (key, val)) %}
+          {% endfor %}
+          {% set attributeString = attributeString | join(" ") -%}
+          <a {{ attributeString }}>
+            {%- if type == "fontawesome" -%}
+            <span><i class="{{ icon }} fa-lg" aria-hidden="true"></i></span>
+            <span class="sr-only">{{ name }}</span>
+            {%- elif type == "local" -%}
+            <img src="{{ pathto(icon, 1) }}" class="icon-link-image" alt="{{ name }}"/>
+            {%- elif type == "url" -%}
+            <img src="{{ icon }}" class="icon-link-image" alt="{{ name }}"/>
+            {%- else %}
+            <span>Incorrectly configured icon link. Type must be `fontawesome`, `url` or `local`.</span>
+            {%- endif -%}
+          </a>
+        </li>
+  {%- endif -%}
+{%- endmacro -%}
+{%- if theme_icon_links -%}
+<ul class="navbar-icon-links navbar-nav"
+    aria-label="{{ theme_icon_links_label }}">
+    <li class="nav-item">
+        <a href="https://aiida.net/">
+            <img src="{{ pathto('_static/logo_aiida.svg', 1) }}" alt="AiiDA" class="aiida-logo">
+        </a>
+    </li>
+    {%- for icon_link in theme_icon_links -%}
+        {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"], icon_link.get("type", "fontawesome"), icon_link.get("attributes", {})) -}}
+    {%- endfor %}
+</ul>
+{%- endif -%}

docs/source/_templates/sbt-sidebar-nav.html

@@ -0,0 +1,24 @@
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main">
+    <div class="bd-toc-item navbar-nav active">
+        {% if theme_home_page_in_toc == True %}
+        {#- This mimicks the pydata theme list style so we can append an extra item at the top #}
+        <ul class="nav bd-sidenav bd-sidenav__home-link">
+            <li class="toctree-l1{% if pagename == root_doc %} current active{% endif %}">
+                <a class="reference internal" href="{{ pathto(root_doc) }}">
+                    {{ root_title }}
+                </a>
+            </li>
+        </ul>
+        {% endif -%}
+
+        {# Ref: https://github.com/pydata/pydata-sphinx-theme/blob/ebf7f704879a1cdc6016d6111062103353ac7677/src/pydata_sphinx_theme/__init__.py#L302 #}
+        {{- generate_toctree_html(
+            startdepth=0,
+            kind="sidebar",
+            maxdepth=2,
+            collapse=False,
+            includehidden=True,
+            titles_only=True,
+            show_nav_level=theme_show_navbar_depth) }}
+    </div>
+</nav>

docs/source/conf.py

@@ -14,16 +14,12 @@
 import pathlib
 import time
 
-# Load the dummy profile even if we are running locally, this way the documentation will succeed even if the current
-# default profile of the AiiDA installation does not use a Django backend.
 from aiida.manage.configuration import load_documentation_profile
 
+load_documentation_profile()
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-import aiida_quantumespresso
-
-load_documentation_profile()
 
 # -- Project information -----------------------------------------------------
 
@@ -32,11 +28,6 @@
 Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)),
 Switzerland. All rights reserved"""
 
-# The full version, including alpha/beta/rc tags.
-release = aiida_quantumespresso.__version__
-# The short X.Y version.
-version = '.'.join(aiida_quantumespresso.__version__.split('.')[:2])
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -46,7 +37,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
@@ -61,9 +51,8 @@
 # Setting the intersphinx mapping to other readthedocs
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3.8', None),
-    'aiida': ('https://aiida.readthedocs.io/en/latest/', None),
+    'aiida': ('https://aiida.readthedocs.io/projects/aiida-core/en/latest/', None),
     'aiida_pseudo': ('http://aiida-pseudo.readthedocs.io/en/latest/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
 }
 
 myst_enable_extensions = [
@@ -72,18 +61,13 @@
     'substitution'
 ]
 
-myst_substitutions = {
-    'release': release,
-    'version': version
-}
-
 # Settings for the `autoapi.extenstion` automatically generating API docs
 filepath_docs = pathlib.Path(__file__).parent.parent
 filepath_src = filepath_docs.parent / 'src'
 autoapi_type = 'python'
 autoapi_dirs = [filepath_src]
 autoapi_ignore = [filepath_src / 'aiida_quantumespresso' / '*cli*']
-autoapi_root = str(filepath_docs / 'source' / 'reference' / 'api')
+autoapi_root = str(filepath_docs / 'source' / 'reference' / 'api' / 'auto')
 autoapi_keep_files = True
 autoapi_add_toctree_entry = False
 
@@ -104,18 +88,24 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['**.ipynb_checkpoints', 'reference/api/auto/aiida_quantumespresso/index.rst']
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_book_theme'
 html_theme_options = {
+    'repository_url': 'https://github.com/aiidateam/aiida-quantumespresso',
     'github_url': 'https://github.com/aiidateam/aiida-quantumespresso',
     'twitter_url': 'https://twitter.com/aiidateam',
     'use_edit_page_button': True,
+    'logo': {
+        'text': 'AiiDA Quantum ESPRESSO',
+        'image_light': '_static/logo_aiida_quantumespresso-light.png',
+        'image_dark': '_static/logo_aiida_quantumespresso-dark.png',
+    }
 }
 html_static_path = ['_static']
 html_context = {
@@ -125,10 +115,12 @@
     'doc_path': 'docs/source',
     'default_mode': 'light',
 }
+html_sidebars = {
+    '**': ['navbar-logo.html', 'navbar-icon-links.html', 'search-field.html', 'sbt-sidebar-nav.html']
+}
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = 'images/logo_docs.png'
 html_static_path = ['_static']
 html_css_files = ['aiida-custom.css', 'aiida-qe-custom.css']
 
@@ -146,80 +138,18 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'aiida-quantumespressodoc'
 
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
-
-    # Latex figure (float) alignment
-    #'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-# latex_documents = [
-# ]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-# man_pages = [
-# ]
-
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-# texinfo_documents = [
-# ]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+# ------------------------------------------------------------------------------
 
 # Warnings to ignore when using the -n (nitpicky) option
 # We should ignore any python built-in exception, for instance
+nitpicky = True
+
+nitpick_ignore_regex = [
+    (r'py:.*', r'pydantic.*'),
+    (r'py:.*', r'con.*'),
+    (r'.*', r'Literal.*'),
+    (r'.*', r'Tuple.*'),
+]
 nitpick_ignore = [
     ('py:exc', 'ArithmeticError'),
     ('py:exc', 'AssertionError'),

docs/source/howto/calculations/index.md

@@ -1,6 +1,11 @@
 (howto-calculations)=
 
-# How-to run calculations
+# Calculations
+
+:::{important}
+The following how-to guides assume that you are familiar with the basics of AiiDA, such as creating data and running processes.
+At the very least, make sure you have followed and understand the tutorial on [running a calculation through the API](#tutorials-pw-through-api).
+:::
 
 ```{toctree}
 :maxdepth: 1

docs/source/howto/workflows/index.md

@@ -1,6 +1,6 @@
 (howto-workflows)=
 
-# How-to run workflows
+# Workflows
 
 ```{toctree}
 :maxdepth: 1