Update and add tutorial

docs/Makefile

@@ -28,6 +28,7 @@ all: clean html view
 
 clean:
 	rm -rf $(BUILDDIR)
+	rm -rf $(shell find . -type d -wholename "*/reference/api/auto")
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/source/_static/aiida-custom.css

@@ -112,6 +112,19 @@ div.admonition :last-child {
 div.highlight-bash div.highlight {
     background-color: aliceblue;
 }
+
 div.highlight-console div.highlight {
     background-color: aliceblue;
 }
+
+.aiida-green {
+    color: #32B805;
+}
+
+.aiida-blue {
+    color: #0496DE;
+}
+
+.aiida-orange {
+    color: #FF7D16;
+}

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

@@ -26,14 +26,33 @@ img.logo__image {
     font-size: 40px!important;
 }
 
-img.aiida-logo {
+img.aiida-sidebar-logo {
     height: 40px!important;
 }
 
+img.aiida-logo {
+    width: 20px;
+    padding-bottom: 3px;
+}
+
 .fa {
     color: var(--pst-color-primary);
 }
 
 .bd-search {
     padding: 0 1rem;
 }
+
+.tutor-footer {
+    padding-top: 0rem;
+    border-top: none!important;
+}
+
+.footer-table {
+    margin-bottom: 0rem;
+    border-color: transparent;
+}
+
+.footer-table td:last-child {
+    text-align: right;
+}

docs/source/_templates/icon-links.html

@@ -30,7 +30,7 @@
     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">
+            <img src="{{ pathto('_static/logo_aiida.svg', 1) }}" alt="AiiDA" class="aiida-sidebar-logo">
         </a>
     </li>
     {%- for icon_link in theme_icon_links -%}

docs/source/conf.py

@@ -30,9 +30,6 @@
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -55,12 +52,6 @@
     'aiida_pseudo': ('http://aiida-pseudo.readthedocs.io/en/latest/', None),
 }
 
-myst_enable_extensions = [
-    'deflist',
-    'colon_fence',
-    'substitution'
-]
-
 # Settings for the `autoapi.extenstion` automatically generating API docs
 filepath_docs = pathlib.Path(__file__).parent.parent
 filepath_src = filepath_docs.parent / 'src'
@@ -90,6 +81,32 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['**.ipynb_checkpoints', 'reference/api/auto/aiida_quantumespresso/index.rst']
 
+# -- MyST options
+
+myst_enable_extensions = [
+    'deflist',
+    'colon_fence',
+    'substitution',
+    'attrs_inline',
+    'substitution'
+]
+
+myst_substitutions = {
+    'aiida_logo': '<img src="../_static/logo_aiida.svg" alt="aiida" class="aiida-logo">',
+    'create_magnetic_configuration': \
+        '{func}`~aiida_quantumespresso.calculations.functions.create_magnetic_configuration.create_magnetic_configuration`',
+    'get_builder_from_protocol': \
+        '{meth}`~aiida_quantumespresso.workflows.pw.base.PwBaseWorkChain.get_builder_from_protocol`',
+    'get_magnetic_configuration': \
+        '{meth}`~aiida_quantumespresso.tools.calculations.pw.PwCalculationTools.get_magnetic_configuration`',
+    'nspin': '[`nspin`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm412)',
+    'PwBaseWorkChain': '{class}`~aiida_quantumespresso.workflows.pw.base.PwBaseWorkChain`',
+    'PwCalculation': '{class}`~aiida_quantumespresso.calculations.pw.PwCalculation`',
+    'SpinType': '{class}`~aiida_quantumespresso.common.types.SpinType`',
+    'starting_magnetization': '[`starting_magnetization`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm299)',
+    'StructureData': '{class}`~aiida.orm.StructureData',
+}
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -209,6 +226,4 @@
     ('py:obj', 'Mapping'),
     ('py:obj', 'qe_tools.parsers.CpInputFile'),
     ('py:obj', 'qe_tools.parsers.PwInputFile'),
-    ('py:class', 'StructureData'),
-    ('py:class', 'PseudoPotentialFamily'),
 ]

docs/source/howto/calculations/ph.md

@@ -16,18 +16,18 @@ In order to run a `ph.x` calculation, you first need to have completed a `pw.x`
 See the [tutorial](#tutorials-pw-through-api) or [how-to guide](#howto-calculations-pw) for more information.
 :::
 
-Once you have successfully run a `PwCalculation` you can run a `ph.x` calculation through the `PhCalculation` plugin as follows:
+Once you have successfully run a {{ PwCalculation }} you can run a `ph.x` calculation through the `PhCalculation` plugin as follows:
 
 ```{literalinclude} ../../tutorials/include/scripts/run_ph_basic.py
 :language: python
 ```
 
-Note that you will have to replace `IDENTIFIER_PW_CALCULATION` with the identifier (pk or UUID) of the completed `PwCalculation`.
+Note that you will have to replace `IDENTIFIER_PW_CALCULATION` with the identifier (pk or UUID) of the completed {{ PwCalculation }}.
 
 ## How to define input file parameters
 
 The `ph.x` code supports many parameters that can be defined through the input file, as shown on the [official documentation](https://www.quantum-espresso.org/Doc/INPUT_PH.html).
-Parameters that are part of the `INPUTPH` card should be specified through the `parameters` input of the `PwCalculation` plugin.
+Parameters that are part of the `INPUTPH` card should be specified through the `parameters` input of the {{ PwCalculation }} plugin.
 The parameters are specified using a Python dictionary, for example:
 
 ```python

docs/source/howto/calculations/pw.md

@@ -18,7 +18,7 @@ Examples of these properties include ground-state energy and one-electron (Kohn-
 
 ## How to launch a `pw.x` calculation
 
-Below is a script with a basic example of how to run a `pw.x` calculation through the `PwCalculation` plugin that computes the electronic ground state of an fcc silicon crystal:
+Below is a script with a basic example of how to run a `pw.x` calculation through the {{ PwCalculation }} plugin that computes the electronic ground state of an fcc silicon crystal:
 
 ```{literalinclude} ../../tutorials/include/scripts/run_pw_basic.py
 :language: python
@@ -30,7 +30,7 @@ Note that you may have to change the name of the code that is loaded using `load
 
 The `pw.x` code supports many parameters that can be defined through the input file, as shown on the [official documentation](https://www.quantum-espresso.org/Doc/INPUT_PW.html).
 The parameters are divided into section or "cards".
-Parameters that are part of cards that start with an ampersand (`&`) should be specified through the `parameters` input of the `PwCalculation` plugin.
+Parameters that are part of cards that start with an ampersand (`&`) should be specified through the `parameters` input of the {{ PwCalculation }} plugin.
 The parameters are specified using a Python dictionary, where each card is its own sub-dictionary, for example:
 
 ```python
@@ -78,13 +78,15 @@ These include:
 Defining them anyway will result in an exception when launching the calculation.
 :::
 
+(howto-calculations-pw-multidimensional-parameters)=
+
 ### Multidimensional parameters
 
 The input format of `pw.x` contains various keywords that do not simply take the format of a key value pair, but rather there will some indices in the key itself.
 Take for example the [`starting_magnetization`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm287) keyword of the `SYSTEM` card.
 The starting magnetization value needs to be applied to a specific species and therefore the index `i` is required to be able to make this distinction.
 
-The `PwCalculation` plugin makes this easy as it will do the conversion from kind name to species index automatically.
+The {{ PwCalculation }} plugin makes this easy as it will do the conversion from kind name to species index automatically.
 This allows you to specify a starting magnetization value by using a dictionary notation, where the key is the kind name to which it should be applied.
 For example, if you have a structure with the kind `Co` and want it to have a given starting magnetization, one can add the following in the parameter data dictionary:
 
@@ -171,7 +173,7 @@ Assuming the input structure contained the kinds `Ni` and `Fe`, which would have
 ## How to define pseudopotentials
 
 Each `pw.x` calculation requires a pseudopotential to be specified for each kind in the structure.
-These pseudopotentials can be specified in the `PwCalculation` plugin through the `pseudos` input namespace.
+These pseudopotentials can be specified in the {{ PwCalculation }} plugin through the `pseudos` input namespace.
 This input takes a dictionary, where the keys are the kind names and the values are instances of the {class}`~aiida_pseudo.data.pseudo.upf.UpfData` data plugin of the {{ aiida_pseudo }} plugin package.
 For example, if the input structure is a `GaAs` crystal, the pseudopotentials could be specified as follows:
 
@@ -263,7 +265,7 @@ builder.settings = Dict({'GAMMA_ONLY': True})
 ## How to fix the coordinates of atoms
 
 Quantum ESPRESSO pw.x allows to optionally fix the coordinates of atoms during relaxation and molecular-dynamics simulations.
-This functionality is enabled in `PwCalculation` through the `FIXED_COORDS` setting which is a list of length equal to the number of sites in the input structure.
+This functionality is enabled in {{ PwCalculation }} through the `FIXED_COORDS` setting which is a list of length equal to the number of sites in the input structure.
 Each element is a list of length three containing booleans, where `True` means that the position of the site in that direction should be fixed.
 For example:
 
@@ -277,7 +279,7 @@ All other coordinates are allowed to change.
 
 ## How to retrieve additional files
 
-The `PwCalculation` plugin will retrieve the most important and common output files by default.
+The {{ PwCalculation }} plugin will retrieve the most important and common output files by default.
 To retrieve additional output files, specify the list of files in the `ADDITIONAL_RETRIEVE_LIST` key in the `settings` input:
 
 ```python
@@ -288,13 +290,13 @@ builder.settings = Dict({'ADDITIONAL_RETRIEVE_LIST': ['custom-file.txt', 'some-o
 
 ## How to analyze the results
 
-When a `PwCalculation` is completed, there are quite a few possible analyses to perform.
+When a {{ PwCalculation }} is completed, there are quite a few possible analyses to perform.
 
 ### How to check the SCF accuracy during the self-consistent cycle
 
 During the self-consistent field cycle, the difference in energy of the newly computed charge density and the starting one is computed and stored.
 It can easily be retrieved through the {meth}`~aiida_quantumespresso.tools.calculations.pw.PwCalculationTools.get_scf_accuracy` method.
-This method can be accessed directly through the ``tools`` of a completed ``PwCalculation`` node:
+This method can be accessed directly through the ``tools`` of a completed `{{ PwCalculation }}` node:
 
 ```python
 In [1]: node = load_node(IDENTIFIER)