Docs: add the documentation 📓 (#36)

A documentation with Myst-NB is added to guide through
the different workflows and package new and current users.

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# C extensions
+*.so
+
 # Distribution / packaging
 .Python
 env/
@@ -21,3 +24,93 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+
+# Dev
+.vscode
+.history/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+*~
+.DS_Store
+.idea
+submit_test/
+_aiida_*
+sssp_pseudos
+# Autogenerated API docs
+docs/source/reference/api/aiida_quantumespresso_hp
+docs/source/reference/cli

.pre-commit-config.yaml

@@ -7,6 +7,11 @@ repos:
     -   id: fix-encoding-pragma
     -   id: mixed-line-ending
     -   id: trailing-whitespace
+        exclude: >-
+            (?x)^(
+                tests/.*.*out|
+                tests/.*.in$
+            )$
 
 -   repo: https://github.com/ikamensh/flynt/
     rev: '0.76'
@@ -25,6 +30,11 @@ repos:
         name: yapf
         types: [python]
         args: ['-i']
+        exclude: &exclude_files >
+            (?x)^(
+                docs/.*|
+                tests/.*(?<!\.py)$
+            )$
         additional_dependencies: ['toml']
 
 -   repo: https://github.com/PyCQA/pylint
@@ -37,8 +47,5 @@ repos:
     rev: '6.1.1'
     hooks:
     -   id: pydocstyle
-        exclude: >
-            (?x)^(
-                src/aiida_quantumespresso_hp/workflows/hubbard.py|
-            )$
+        exclude: *exclude_files
         additional_dependencies: ['toml']

.readthedocs.yml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  apt_packages:
+      - quantum-espresso
+
+conda:
+  environment: environment.yml
+
+python:
+    install:
+        - method: pip
+          path: .
+          extra_requirements:
+            - docs
+
+sphinx:
+    configuration: docs/source/conf.py
+    fail_on_warning: false

docs/Makefile

@@ -0,0 +1,40 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+AIIDAWORKDIR  = source/local_module/_aiida_*
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault
+
+customdefault:
+	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+all: html view
+
+clean:
+	rm -rf $(BUILDDIR); rm -rf $(AIIDAWORKDIR)
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+
+view:
+	open $(BUILDDIR)/html/index.html