Docs: Switch to using MyST Markdown

Convert the entire documentation in MyST Markdown, which is easier to use due
to its similarity with the ubiquitous Markdown and cleaner syntax:

https://myst-parser.readthedocs.io/en/latest/index.html

Moving to MyST Markdown also makes it easier/more consistent to use MyST-NB:

https://myst-nb.readthedocs.io/en/latest/index.html

and eventually move to fully executable documentation.

Some remaining RestructuredText elements:

* The `autodoc` generation of the API. 
* Automated generation of CLI documentation.
* `aiida.sphinxext` items.

docs/Makefile

@@ -24,7 +24,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 customdefault:
 	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
-all: html
+all: html view
 
 clean:
 	rm -rf $(BUILDDIR)
@@ -36,4 +36,4 @@ html:
 
 
 view:
-	xdg-open $(BUILDDIR)/html/index.html
+	open $(BUILDDIR)/html/index.html

docs/source/conf.py

@@ -51,17 +51,30 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx_copybutton',
-    'sphinx_click',
+    'sphinx_click.ext',
     'sphinx_design',
+    'myst_parser',
     'aiida.sphinxext',
     'autoapi.extension',
 ]
 
 # Setting the intersphinx mapping to other readthedocs
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3.8', None),
-    'aiida': ('http://aiida.readthedocs.io/en/latest/', None),
+    'aiida': ('https://aiida.readthedocs.io/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 = [
+    'deflist',
+    'colon_fence',
+    'substitution'
+]
+
+myst_substitutions = {
+    'release': release,
+    'version': version
 }
 
 # Settings for the `autoapi.extenstion` automatically generating API docs
@@ -87,7 +100,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -110,6 +123,7 @@
     'github_repo': 'aiida-quantumespresso',
     'github_version': 'main',
     'doc_path': 'docs/source',
+    'default_mode': 'light',
 }
 
 # The name of an image file (relative to this directory) to place at the top

docs/source/howto/calculations/cp.md

@@ -0,0 +1,5 @@
+(howto-calculations-cp)=
+
+# `cp.x`
+
+*To be added.*

docs/source/howto/calculations/dos.md

@@ -0,0 +1,5 @@
+(howto-calculations-dos)=
+
+# `dos.x`
+
+*To be added.*

docs/source/howto/calculations/epw.md

@@ -0,0 +1,5 @@
+(howto-calculations-epw)=
+
+# `epw.x`
+
+*To be added.*

docs/source/howto/calculations/index.md

@@ -0,0 +1,20 @@
+(howto-calculations)=
+
+# How-to run calculations
+
+```{toctree}
+:maxdepth: 1
+
+cp
+dos
+epw
+matdyn
+neb
+ph
+pp
+projwfc
+pw
+pw2wannier90
+q2r
+xspectra
+```

docs/source/howto/calculations/matdyn.md

@@ -0,0 +1,5 @@
+(howto-calculations-matdyn)=
+
+# `matdyn.x`
+
+*To be added.*

docs/source/howto/calculations/neb.md

@@ -0,0 +1,5 @@
+(howto-calculations-neb)=
+
+# `neb.x`
+
+*To be added.*

docs/source/howto/calculations/ph.md

@@ -0,0 +1,69 @@
+(howto-calculations-ph)=
+
+# `ph.x`
+
+The `ph.x` code of Quantum ESPRESSO is used to compute phonons using density-functional perturbation theory.
+
+|                     |                                                               |
+|---------------------|---------------------------------------------------------------|
+| Plugin class        | {class}`aiida_quantumespresso.calculations.ph.PhCalculation`  |
+| Plugin entry point  | ``quantumespresso.ph``                                        |
+
+## How to launch a `ph.x` calculation
+
+:::{note}
+In order to run a `ph.x` calculation, you first need to have completed a `pw.x` calculation.
+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:
+
+```{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`.
+
+## 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.
+The parameters are specified using a Python dictionary, for example:
+
+```python
+parameters = {
+    'INPUTPH': {
+        'tr2_ph' : 1.0e-8,
+        'epsil' : True,
+        'ldisp' : True,
+    }
+}
+```
+
+The parameters dictionary should be wrapped in a {py:class}`~aiida.orm.nodes.data.dict.Dict` node and assigned to the `parameters` input of the process builder:
+
+```python
+from aiida.orm import Dict, load_code
+builder = load_code('ph').get_builder()
+parameters = {
+    ...
+}
+builder.parameters = Dict(parameters)
+```
+
+The q-points of the input file are specified with a `KpointsData` node through the `qpoints` input of the `PhCalculation` plugin.
+
+:::{warning}
+There are a number of input parameters that *cannot* be set, as they will be automatically set by the plugin based on other inputs, such as the `structure`.
+These include:
+
+- `INPUTPH.outdir`
+- `INPUTPH.verbosity`
+- `INPUTPH.prefix`
+- `INPUTPH.fildyn`
+- `INPUTPH.ldisp`
+- `INPUTPH.nq1`
+- `INPUTPH.nq2`
+- `INPUTPH.nq3`
+- `INPUTPH.qplot`
+:::

docs/source/howto/calculations/pp.md

@@ -0,0 +1,5 @@
+(howto-calculations-pp)=
+
+# `pp.x`
+
+*To be added.*

docs/source/howto/calculations/projwfc.md

@@ -0,0 +1,5 @@
+(howto-calculations-projwfc)=
+
+# `projwfc.x`
+
+*To be added.*