Merge pull request #96 from aiidateam/tutorial_2019_05

add tutorial 2019-05 on writing reproducible workflows

.gitignore

@@ -1,3 +1,10 @@
 *~
 .DS_Store
 *.swp
+*.pyc
+
+.vscode
+docs/build
+docs/_build
+
+.ipynb_checkpoints

.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+# # Install pre-commit hooks via
+# pre-commit install
+
+# modernizer: make sure our code-base is Python 3 ready
+- repo: https://github.com/python-modernize/python-modernize.git
+  sha: 5650894e684250b8dd7a7d552adeea98eb8663ba
+  hooks:
+  - id: python-modernize
+    exclude: &exclude_files >
+      (?x)^(
+        docs/pages/2019_molsim_school_Amsterdam/assets/raspa_loading.py|
+        docs/assets/2018_PRACE_MaX/latex/de-macro.py|
+        docs/pages/2019_MARVEL_Psik_MaX/sections/include/snippets/.*|
+        docs/pages/2019_molsim_school_Amsterdam/assets/multiply_unitcell.py
+      )$
+    args:
+      - --write
+      - --nobackups
+
+- repo: local
+  hooks:
+  # yapf = yet another python formatter
+  - id: yapf
+    name: yapf
+    entry: yapf
+    language: system
+    types: [python]
+    args: ["-i"]
+    exclude: *exclude_files
+
+  # prospector: collection of linters
+  - id: prospector
+    language: system
+    types: [file, python]
+    name: prospector
+    description: "This hook runs Prospector: https://github.com/landscapeio/prospector"
+    entry: prospector
+    exclude: *exclude_files

.pylintrc

@@ -0,0 +1,21 @@
+[MESSAGES CONTROL]
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once). You can also use "--disable=all" to
+# disable everything first and then reenable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use "--disable=all --enable=classes
+# --disable=W".
+disable=import-error,
+        locally-disabled,
+        invalid-name,
+        relative-beyond-top-level
+
+
+[FORMAT]
+
+# Maximum number of characters on a single line.
+max-line-length=120

.readthedocs.yml

@@ -17,4 +17,4 @@ formats: []
 python:
   version: 3.7
   install:
-    - requirements: docs/requirements.txt
+    - requirements: requirements.txt

.travis.yml

@@ -1,14 +1,44 @@
 language: python
 python:
- - "2.7"
- - "3.6"
-sudo: required
+  - "3.6"
 
-before_install:
-  - sudo apt-get install pandoc
+addons:
+  apt:
+    packages:
+      # for jupyter notebook rendering
+      - pandoc
+      # for building latex/pdf
+      - texlive-base
+      - texlive-generic-recommended
+      - texlive-fonts-recommended
+      - texlive-latex-base
+      - texlive-latex-recommended
+      - texlive-latex-extra
+      - latexmk
+      - latex-xcolor
+      - dvipng
+      - dvidvi
+
+env:
+  matrix:
+    - BUILD: docs
+      TARGET: html
+      SPHINXOPTS: -W
+    - BUILD: docs
+      TARGET: latexpdf
+    - BUILD: pre-commit
 
 install:
   - pip install --upgrade pip
-  - pip install -r docs/requirements.txt
+  - pip install -r requirements.txt
 
-script: cd docs; make
+script: 
+  - >
+    if [ "$BUILD" == "docs" ]; then 
+     # -C docs: switch to docs/ directory
+      make -C docs pre-docs
+      make -C docs $TARGET
+    else
+      pre-commit install
+      pre-commit run --all-files || ( git status --short; git diff ; exit 1 )
+    fi

README.md

@@ -26,19 +26,25 @@ If you have a question, feel free to just [open an issue](https://github.com/aii
 
 ### Prerequisites
 
- * python 2.7 or greater
+ * python 3.5 or greater
  * [pandoc](https://pandoc.org/)
 
 ### Build instructions
 
-```
+```bash
 git clone https://github.com/aiidateam/aiida-tutorials.git
-cd aiida-tutorials/docs
+cd aiida-tutorials
 pip install -r requirements.txt
+pre-commit install   # enable pre-commit hooks (optional)
+cd docs/
 make
 # open build/html/index.html
 ```
 
+Note that `make` will run with the nitpick option, treating warnings as errors.
+If you are updating the documentation and warnings are expected, run `make html` instead.
+This does not use the nitpick exception and will ensure that the documentation compiles despite the warnings.
+
 ## Acknowledgements
 
 This work is supported by the [MARVEL National Centre for Competency in Research](<http://nccr-marvel.ch>)

docs/Makefile

@@ -1,5 +1,4 @@
 # Makefile for Sphinx documentation
-#
 
 # You can set these variables from the command line.
 #SPHINXOPTS    =
@@ -14,16 +13,38 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext all default
+# Note: if you don't want to directly include the solutions in the HTML documentation
+# but just make it downloadable, remember to add the path to the `exclude_patterns`
+# in the `conf.py` file
+IPYNB_TEMPATE_PATTERNS = $(patsubst %-template.ipynb, %-tutorial.ipynb, $(wildcard pages/*/notebooks/querybuilder-template.ipynb)) $(patsubst %-template.ipynb, %-solutions.ipynb, $(wildcard pages/*/notebooks/querybuilder-template.ipynb))
 
-default:
-	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext all default defaultdoc templatenotebooks cleannotebooks pre-docs
 
-# Same as 'default' but does not exit at the first warning
-debug:
-	$(SPHINXBUILD) -b html -n $(ALLSPHINXOPTS) $(BUILDDIR)/html
+# First make notebooks, then docs
+default: pre-docs defaultdoc
+
+# Everything needed before compiling the docs
+# This is automatically taken into account above by the 'default' target,
+# that since it is the first one, it will be run when executing 'make' without
+# parameters. However, this must also be called "by hand" in Travis
+pre-docs: templatenotebooks
+
+templatenotebooks: $(IPYNB_TEMPATE_PATTERNS)
+
+%-tutorial.ipynb: %-template.ipynb
+	python scripts/make_notebook.py -t $@ $<
+
+%-solutions.ipynb: %-template.ipynb
+	python scripts/make_notebook.py -s $@ $<
+
+cleannotebooks:
+	rm -f $(IPYNB_TEMPATE_PATTERNS)
+
+# -W: exit on warning
+defaultdoc:
+	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
-all: html
+all: html latexpdf
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -47,7 +68,7 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
-clean:
+clean: cleannotebooks
 	-rm -rf $(BUILDDIR)
 
 html:

docs/_static/css/custom.css

@@ -1,3 +1,8 @@
 div.highlight-console div.highlight {
     background-color: aliceblue;
 }
+
+div.highlight-bash div.highlight {
+    background-color: aliceblue;
+}
+