Merge be2e1f0 into 719843c

.readthedocs.yml

@@ -0,0 +1,7 @@
+build:
+  image: latest
+python:
+  version: 3.6
+  pip_install: true
+  extra_requirements:
+  - "docs"

.travis.yml

@@ -13,6 +13,7 @@ script:
   - "echo \"Docker ID: $DOCKERID\""
   - docker exec -it --user aiida $DOCKERID /bin/bash -l -c 'cd /opt/aiida-cp2k/ && pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )'
   - docker exec -it --user aiida $DOCKERID /bin/bash -l -c 'cd /opt/aiida-cp2k/ && py.test --cov aiida_cp2k --cov-append .'
+  - docker exec -it --user aiida $DOCKERID /bin/bash -l -c 'cd /opt/aiida-cp2k/docs && make'
 
 after_success:
   - docker exec -e TRAVIS=$TRAVIS -e TRAVIS_JOB_ID=$TRAVIS_JOB_ID -e TRAVIS_BRANCH=$TRAVIS_BRANCH -it --user aiida $DOCKERID /bin/bash -l -c 'cd /opt/aiida-cp2k/ && coveralls'

Dockerfile

@@ -21,7 +21,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends cp2k
 
 # Install aiida-cp2k plugin.
 COPY . aiida-cp2k
-RUN pip install ./aiida-cp2k[pre-commit,test]
+RUN pip install ./aiida-cp2k[pre-commit,test,docs]
 
 # Install coverals.
 RUN pip install coveralls

aiida_cp2k/utils/input_generator.py

@@ -41,14 +41,18 @@ def add_keyword(self, kwpath, value, override=True, conflicting_keys=None):
         Add a value for the given keyword.
 
         Args:
+
             kwpath: Can be a single keyword, a path with `/` as divider for sections & key,
-                    or a sequence with sections and key
+                    or a sequence with sections and key.
+
             value: the value to set the given key to
+
             override: whether to override the key if it is already present in the self._params
+
             conflicting_keys: list of keys that cannot live together with the provided key
-                              (SOMETHING1/[..]/SOMETHING2/KEY). In case override is True, all conflicting keys will
-                              be removed, if override is False and conflicting_keys are present the new key won't be
-                              added.
+            (SOMETHING1/[..]/SOMETHING2/KEY). In case override is True, all conflicting keys will
+            be removed, if override is False and conflicting_keys are present the new key won't be
+            added.
         """
 
         if isinstance(kwpath, six.string_types):
@@ -101,35 +105,34 @@ def _add_keyword(kwpath, value, params, ovrd, cfct):
 
     @staticmethod
     def _render_section(output, params, indent=0):
-        """
-        It takes a dictionary and recurses through.
+        """It takes a dictionary and recurses through.
 
-        For key-value pair it checks whether the value is a dictionary
-        and prepends the key with & (CP2K section)
-        It passes the valued to the same function, increasing the indentation
-        If the value is a list, I assume that this is something the user
-        wants to store repetitively
+        For key-value pair it checks whether the value is a dictionary and prepends the key with & (CP2K section).
+        It passes the valued to the same function, increasing the indentation. If the value is a list, I assume
+        that this is something the user wants to store repetitively
         eg:
-            dict['KEY'] = ['val1', 'val2']
-            ===>
-            KEY val1
-            KEY val2
-
-            or
-
-            dict['KIND'] = [{'_': 'Ba', 'ELEMENT':'Ba'},
-                            {'_': 'Ti', 'ELEMENT':'Ti'},
-                            {'_': 'O', 'ELEMENT':'O'}]
-            ====>
-                  &KIND Ba
-                     ELEMENT  Ba
-                  &END KIND
-                  &KIND Ti
-                     ELEMENT  Ti
-                  &END KIND
-                  &KIND O
-                     ELEMENT  O
-                  &END KIND
+        .. highlight::
+
+           dict['KEY'] = ['val1', 'val2']
+           ===>
+           KEY val1
+           KEY val2
+
+           or
+
+           dict['KIND'] = [{'_': 'Ba', 'ELEMENT':'Ba'},
+                           {'_': 'Ti', 'ELEMENT':'Ti'},
+                           {'_': 'O', 'ELEMENT':'O'}]
+           ====>
+                 &KIND Ba
+                    ELEMENT  Ba
+                 &END KIND
+                 &KIND Ti
+                    ELEMENT  Ti
+                 &END KIND
+                 &KIND O
+                    ELEMENT  O
+                 &END KIND
         """
 
         for key, val in sorted(params.items()):

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/Makefile

@@ -0,0 +1,42 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# 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
+
+## Runs with nitty-pick and converting warnings into errors to 
+## make sure the documentation is properly written
+customdefault:
+	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+all: html
+
+clean:
+	rm -r $(BUILDDIR)
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+
+view:
+	xdg-open $(BUILDDIR)/html/index.html
+

docs/source/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 800px !important;
+}

docs/source/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

docs/source/apidoc/.gitignore

@@ -0,0 +1 @@
+*