Docs revamp

.circleci/config.yml

@@ -0,0 +1,40 @@
+version: 2
+jobs:
+  docs:
+    docker:
+      # see: https://circleci.com/docs/2.0/circleci-images/#python
+      - image: circleci/python:3.7-stretch
+    steps:
+      # Get our data and merge with upstream
+      - run: sudo apt-get update
+      - checkout
+
+      - restore_cache:
+          keys:
+            - cache-pip
+
+      - run: |
+          pip install numpy==1.17.4
+          pip install --user .[docs,testing]
+
+      - save_cache:
+          key: cache-pip
+          paths:
+            - ~/.cache/pip
+
+      # Build the docs
+      - run:
+          name: Build docs to store
+          # nit-picky mode, turn warnings into errors,
+          # but do not stop the build on errors (so we can still inspect the doc artifacts)
+          command: |
+            sphinx-build -b html -n -W --keep-going -d docs/_build/doctrees docs/source docs/_build/html
+      - store_artifacts:
+          path: docs/_build/html/
+          destination: html
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - docs

.github/workflows/ci.yml

@@ -4,37 +4,6 @@ on: [push, pull_request]
 
 jobs:
 
-  docs:
-
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-
-    steps:
-    - uses: actions/checkout@v2
-
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-
-    - name: Install system dependencies
-      # remove occasionally problematic repositories we don't use anyway
-      run: |
-        sudo rm -f /etc/apt/sources.list.d/dotnetdev.list /etc/apt/sources.list.d/microsoft-prod.list
-        sudo apt update
-        sudo apt install texlive-base texlive-generic-recommended texlive-fonts-recommended texlive-latex-base texlive-latex-recommended texlive-latex-extra dvipng dvidvi
-
-    - name: Install python dependencies
-      run: |
-        pip install numpy==1.17.4
-        pip install -e .[docs,testing]
-
-    - name: Build documentation
-      env:
-        READTHEDOCS: 'True'
-      run:
-        SPHINXOPTS='-nW' make -C docs html
-
   pre-commit:
 
     runs-on: ubuntu-latest

README.md

@@ -45,6 +45,10 @@ Small improvements of the documentation or minor bug fixes are always welcome.
 
 Please see the [Contributor wiki](/~https://github.com/aiidateam/aiida-core/wiki) on how to get started.
 
+## Frequently Asked Questions
+
+If you are experiencing problems with your AiiDA installation, please refer to the [FAQ page of the documentation](https://aiida-core.readthedocs.io/en/latest/howto/faq.html).
+
 ## How to cite
 
 If you use AiiDA in your research, please consider citing the AiiDA paper:

aiida/tools/dbimporters/plugins/icsd.py

@@ -36,8 +36,6 @@ class IcsdDbImporter(DbImporter):
     """
     Importer for the Inorganic Crystal Structure Database, short ICSD, provided by
     FIZ Karlsruhe. It allows to run queries and analyse all the results.
-    See the :ref:`DbImporter documentation and
-    tutorial page <ICSD_importer_guide>` for more information.
 
     :param server: Server URL, the web page of the database. It is
         required in order to have access to the full database.

aiida/tools/visualization/graph.py

@@ -513,7 +513,7 @@ def add_incoming(self, node, link_types=(), annotate_links=None, return_pks=True
             )
 
         # incoming nodes are found traversing backwards
-        node_pk = node if isinstance(node, int) else node.pk
+        node_pk = self._load_node(node).pk
         valid_link_types = self._default_link_types(link_types)
         valid_link_types = self._convert_link_types(valid_link_types)
         traversed_graph = traverse_graph(
@@ -570,7 +570,7 @@ def add_outgoing(self, node, link_types=(), annotate_links=None, return_pks=True
             )
 
         # outgoing nodes are found traversing forwards
-        node_pk = node if isinstance(node, int) else node.pk
+        node_pk = self._load_node(node).pk
         valid_link_types = self._default_link_types(link_types)
         valid_link_types = self._convert_link_types(valid_link_types)
         traversed_graph = traverse_graph(
@@ -647,7 +647,7 @@ def recurse_descendants(
 
         # Get graph traversal rules where the given link types and direction are all set to True,
         # and all others are set to False
-        origin_pk = origin if isinstance(origin, int) else origin.pk
+        origin_pk = self._load_node(origin).pk
         valid_link_types = self._default_link_types(link_types)
         valid_link_types = self._convert_link_types(valid_link_types)
         traversed_graph = traverse_graph(
@@ -742,7 +742,7 @@ def recurse_ancestors(
 
         # Get graph traversal rules where the given link types and direction are all set to True,
         # and all others are set to False
-        origin_pk = origin if isinstance(origin, int) else origin.pk
+        origin_pk = self._load_node(origin).pk
         valid_link_types = self._default_link_types(link_types)
         valid_link_types = self._convert_link_types(valid_link_types)
         traversed_graph = traverse_graph(

docs/Makefile

@@ -8,7 +8,7 @@ PAPER         =
 BUILDDIR      = build
 
 # Added for sphinx-apidoc
-APIDOCDIR     = source/apidoc
+APIDOCDIR     = source/reference/apidoc
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4

docs/requirements_for_rtd.txt

@@ -29,6 +29,7 @@ plumpy~=0.14.5
 psutil~=5.6
 psycopg2-binary>=2.8.3,~=2.8
 pyblake2~=1.1; python_version < "3.6"
+pydata-sphinx-theme~=0.3.0
 pygments~=2.5
 pymatgen>=2019.7.2
 pymysql~=0.9.3
@@ -44,8 +45,8 @@ reentry~=1.3
 seekpath>=1.9.3,~=1.9
 simplejson~=3.16
 spglib~=1.14
-sphinx-rtd-theme~=0.4.3
-sphinxcontrib-contentui~=0.2.4
+sphinx-copybutton~=0.2.11
+sphinx-panels~=0.4.0
 sphinxcontrib-details-directive~=0.1.0
 sphinx~=2.2
 sqlalchemy-diff~=0.1.3

docs/source/_static/aiida-custom.css

@@ -0,0 +1,117 @@
+/* Fix CSS of top bar link icons */
+a.nav-link.nav-external i {
+    padding-left: 0.3em !important;
+    font-size: inherit !important;
+    vertical-align: inherit !important;
+}
+/* Current fix for /~https://github.com/pandas-dev/pydata-sphinx-theme/issues/193 */
+dl.field-list {
+    display: grid;
+    grid-template-columns: fit-content(30%) minmax(0, 1fr);
+}
+/* For icon unicodes see https://fontawesome.com/v4.7.0/icons/  */
+.title-icon-rocket .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f135"
+}
+.title-icon-info-circle .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f05a"
+}
+.title-icon-question-circle .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f059"
+}
+.title-icon-download .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f019"
+}
+.title-icon-external-link .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f08e"
+}
+.title-icon-lightbulb .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f0eb"
+}
+.title-icon-wrench .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f0ad"
+}
+.title-icon-cog .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f013"
+}
+.title-icon-cogs .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f085"
+}
+.title-icon-code-fork .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f126"
+}
+/* Semantic icon names */
+.title-icon-launch-software .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f135" /* rocket */
+}
+.title-icon-install-software .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f019" /* download */
+}
+.title-icon-information .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f05a" /* info-circle */
+}
+.title-icon-tip .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f0eb" /* lightbulb */
+}
+.title-icon-important .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f06a" /* exclamation-circle */
+}
+.title-icon-warning .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f071" /* exclamation-triangle */
+}
+.title-icon-troubleshoot .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f0ad"  /* wrench */
+}
+.title-icon-read-more .admonition-title:before {
+    margin-right:.5rem;
+    content: "\f518"  /* external-link */
+}
+
+.dropdown-group .dropdown .summary-title {
+    border-bottom: 0 !important;
+    font-weight:700 !important;
+}
+.dropdown-group .dropdown:not(:last-child) {
+    margin-bottom: 0 !important;
+    border-radius: 0 !important;
+}
+.dropdown-group .dropdown:first-child,
+.dropdown-group .dropdown:first-child .summary-title {
+    border-radius: 1rem 1rem 0rem 0rem !important;
+}
+.dropdown-group .dropdown:last-child,
+.dropdown-group .dropdown:last-child .summary-title {
+    border-radius: 0rem 0rem 1rem 1rem !important;
+}
+
+.dropdown-group .dropdown:last-child {
+    margin-bottom: 24px !important;
+}
+
+div.admonition :last-child {
+    margin-bottom: 0
+}
+
+div.highlight-bash div.highlight {
+    background-color: aliceblue;
+}
+div.highlight-console div.highlight {
+    background-color: aliceblue;
+}