Docs: Add first version of documentation

.gitignore

@@ -63,7 +63,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/
@@ -100,3 +100,6 @@ ENV/
 
 # mypy
 .mypy_cache/
+
+# VSCode
+.vscode

.pre-commit-config.yaml

@@ -24,15 +24,21 @@ repos:
         name: yapf
         types: [python]
         args: ['-i']
+        exclude: &exclude_files >
+            (?x)^(
+                docs/.*|
+            )$
 
 -   repo: https://github.com/PyCQA/pylint
     rev: pylint-2.6.0
     hooks:
     -   id: pylint
         language: system
+        exclude: *exclude_files
 
 -   repo: https://github.com/PyCQA/pydocstyle
     rev: 5.0.2
     hooks:
     -   id: pydocstyle
         args: ['--ignore=D104,D203,D213']
+        exclude: *exclude_files

aiida_pseudo/cli/root.py

@@ -8,4 +8,4 @@
 @click.group('aiida-pseudo', context_settings={'help_option_names': ['-h', '--help']})
 @options.PROFILE(type=types.ProfileParamType(load_profile=True))
 def cmd_root(profile):  # pylint: disable=unused-argument
-    """CLI for the `aiida-pseudo` plugin."""
+    """CLI for the ``aiida-pseudo`` plugin."""

aiida_pseudo/groups/family/pseudo_dojo.py

@@ -23,10 +23,10 @@
 
 
 class PseudoDojoFamily(RecommendedCutoffMixin, PseudoPotentialFamily):
-    """Subclass of `PseudoPotentialFfamily` designed to represent a PseudoDojo configuration.
+    """Subclass of ``PseudoPotentialFamily`` designed to represent a PseudoDojo configuration.
 
-    The `PseudoDojoFamily` is essentially a `PseudoPotentialFfamily` with some additional constraints. It can only be
-    used to contain the pseudo potentials and corresponding metadata of an official PseudoDojo configuration.
+    The ``PseudoDojoFamily`` is essentially a ``PseudoPotentialFamily`` with some additional constraints. It can only
+    be used to contain the pseudo potentials and corresponding metadata of an official PseudoDojo configuration.
     """
 
     _pseudo_types = (UpfData, PsmlData, Psp8Data, JthXmlData)

aiida_pseudo/groups/mixins/cutoffs.py

@@ -35,6 +35,8 @@ def validate_cutoffs(elements: set, cutoffs: dict) -> None:
             specifies the ``cutoff_wfc`` and ``cutoff_rho`` keys, corresponding a float value with the recommended
             cutoff to be used for the wave functions and charge density, respectively. For example:
 
+            .. code-block::
+
                 {
                     "Ag": {
                         "cutoff_wfc": 50.0,
@@ -150,14 +152,15 @@ def set_cutoffs(self, cutoffs: dict, stringency: str, unit: str = None) -> None:
             specifies the ``cutoff_wfc`` and ``cutoff_rho`` keys, corresponding a float value with the recommended
             cutoff to be used for the wave functions and charge density, respectively. For example:
 
+            .. code-block::
+
                 {
                     "Ag": {
                         "cutoff_wfc": 50.0,
                         "cutoff_rho": 200.0
                     },
                     ...
                 }
-
         :param stringency: the stringency corresponding to the provided cutoffs.
         :param unit: string definition of a unit of energy as recognized by the ``UnitRegistry`` of the ``pint`` lib.
             Defaults to electronvolt.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# 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
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

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;
+}

docs/source/cli.rst

@@ -0,0 +1,8 @@
+
+#############
+CLI reference
+#############
+
+.. click:: aiida_pseudo.cli.root:cmd_root
+    :prog: aiida-pseudo
+    :nested: full

docs/source/conf.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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 os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+import aiida_pseudo
+
+# -- Project information -----------------------------------------------------
+
+project = 'aiida-pseudo'
+copyright = '2020-2021, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland'
+release = aiida_pseudo.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx_copybutton', 'autoapi.extension', 'sphinx_click']
+
+# Settings for the `sphinx_copybutton` extension
+copybutton_selector = 'div:not(.no-copy)>div.highlight pre'
+copybutton_prompt_text = r'>>> |\.\.\. |(?:\(.*\) )?\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
+copybutton_prompt_is_regexp = True
+
+# Settings for the `autoapi` extension
+autoapi_dirs = ['../../aiida_pseudo']
+autoapi_ignore = ['*cli*']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- 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 = 'sphinx_book_theme'
+html_static_path = ['_static']
+html_css_files = ['aiida-custom.css']
+html_theme_options = {
+    'home_page_in_toc': True,
+    'repository_url': 'https://github.com/aiidateam/aiida-pseudo',
+    'repository_branch': 'master',
+    'use_repository_button': True,
+    'use_issues_button': True,
+    'path_to_docs': 'docs',
+    'use_edit_page_button': True,
+    'extra_navbar': ''
+}
+html_domain_indices = True
+html_logo = '_static/logo.png'