update developer docs

.readthedocs.yml

@@ -1,7 +1,9 @@
-build:
-  image: latest
+version: 2
+
 python:
   version: 3.7
-  pip_install: true
-  extra_requirements:
-  - "docs"
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -32,11 +32,25 @@ intended to help developers get started with their AiiDA plugins.
 * [`LICENSE`](LICENSE): License for your plugin
 * [`MANIFEST.in`](MANIFEST.in): Configure non-Python files to be included for publication on [PyPI](https://pypi.org/)
 * [`README.md`](README.md): This file
-* [`conftest.py`](conftest.py): Configuration of fixtures for [pytest](https://docs.pytest.org/en/latest/) 
-* [`pytest.ini`](pytest.ini): Configuration of [pytest](https://docs.pytest.org/en/latest/) test discovery 
+* [`conftest.py`](conftest.py): Configuration of fixtures for [pytest](https://docs.pytest.org/en/latest/)
+* [`pytest.ini`](pytest.ini): Configuration of [pytest](https://docs.pytest.org/en/latest/) test discovery
 * [`setup.json`](setup.json): Plugin metadata for registration on [PyPI](https://pypi.org/) and the [AiiDA plugin registry](https://aiidateam.github.io/aiida-registry/) (including entry points)
 * [`setup.py`](setup.py): Installation script for pip / [PyPI](https://pypi.org/)
 
+
+See also the following video sequences from the 2019-05 AiiDA tutorial:
+
+ * [aiida-diff setup.json](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=240s)
+ * [run aiida-diff example calculation](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=403s)
+ * [aiida-diff CalcJob plugin](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=685s)
+ * [aiida-diff Parser plugin](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=936s)
+ * [aiida-diff computer/code helpers](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=1238s)
+ * [aiida-diff input data (with validation)](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=1353s)
+ * [aiida-diff cli](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=1621s)
+ * [aiida-diff tests](https://www.youtube.com/watch?v=2CxiuiA1uVs&t=1931s)
+ * [Adding your plugin to the registry](https://www.youtube.com/watch?v=760O2lDB-TM&t=112s)
+ * [pre-commit hooks](https://www.youtube.com/watch?v=760O2lDB-TM&t=333s)
+
 For more information, see the [developer guide](https://aiida-diff.readthedocs.io/en/latest/developer_guide) of your plugin.
 
 

docs/source/conf.py

@@ -52,8 +52,8 @@
 ]
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/2.7', None),
-    'aiida': ('http://aiida-core.readthedocs.io/en/latest/', None),
+    'python': ('https://docs.python.org/3', None),
+    'aiida': ('https://aiida-core.readthedocs.io/en/latest', None),
 }
 
 nitpick_ignore = [('py:obj', 'module')]
@@ -353,61 +353,4 @@ def setup(app):
 
 # Warnings to ignore when using the -n (nitpicky) option
 # We should ignore any python built-in exception, for instance
-nitpick_ignore = [
-    ('py:exc', 'ArithmeticError'),
-    ('py:exc', 'AssertionError'),
-    ('py:exc', 'AttributeError'),
-    ('py:exc', 'BaseException'),
-    ('py:exc', 'BufferError'),
-    ('py:exc', 'DeprecationWarning'),
-    ('py:exc', 'EOFError'),
-    ('py:exc', 'EnvironmentError'),
-    ('py:exc', 'Exception'),
-    ('py:exc', 'FloatingPointError'),
-    ('py:exc', 'FutureWarning'),
-    ('py:exc', 'GeneratorExit'),
-    ('py:exc', 'IOError'),
-    ('py:exc', 'ImportError'),
-    ('py:exc', 'ImportWarning'),
-    ('py:exc', 'IndentationError'),
-    ('py:exc', 'IndexError'),
-    ('py:exc', 'KeyError'),
-    ('py:exc', 'KeyboardInterrupt'),
-    ('py:exc', 'LookupError'),
-    ('py:exc', 'MemoryError'),
-    ('py:exc', 'NameError'),
-    ('py:exc', 'NotImplementedError'),
-    ('py:exc', 'OSError'),
-    ('py:exc', 'OverflowError'),
-    ('py:exc', 'PendingDeprecationWarning'),
-    ('py:exc', 'ReferenceError'),
-    ('py:exc', 'RuntimeError'),
-    ('py:exc', 'RuntimeWarning'),
-    ('py:exc', 'StandardError'),
-    ('py:exc', 'StopIteration'),
-    ('py:exc', 'SyntaxError'),
-    ('py:exc', 'SyntaxWarning'),
-    ('py:exc', 'SystemError'),
-    ('py:exc', 'SystemExit'),
-    ('py:exc', 'TabError'),
-    ('py:exc', 'TypeError'),
-    ('py:exc', 'UnboundLocalError'),
-    ('py:exc', 'UnicodeDecodeError'),
-    ('py:exc', 'UnicodeEncodeError'),
-    ('py:exc', 'UnicodeError'),
-    ('py:exc', 'UnicodeTranslateError'),
-    ('py:exc', 'UnicodeWarning'),
-    ('py:exc', 'UserWarning'),
-    ('py:exc', 'VMSError'),
-    ('py:exc', 'ValueError'),
-    ('py:exc', 'Warning'),
-    ('py:exc', 'WindowsError'),
-    ('py:exc', 'ZeroDivisionError'),
-    ('py:obj', 'str'),
-    ('py:obj', 'list'),
-    ('py:obj', 'tuple'),
-    ('py:obj', 'int'),
-    ('py:obj', 'float'),
-    ('py:obj', 'bool'),
-    ('py:obj', 'Mapping'),
-]
+nitpick_ignore = []

docs/source/developer_guide/index.rst

@@ -37,14 +37,38 @@ Continuous integration
 #. build the documentation
 #. check coding style and version number (not required to pass by default)
 
-Online documentation
-++++++++++++++++++++
+Building the documentation
+++++++++++++++++++++++++++
 
-The documentation of ``aiida-diff``
-is ready for `ReadTheDocs <https://readthedocs.org/>`_:
+ #. Install the ``docs`` extra::
 
-Simply add the ``aiida-diff`` repository on your RTD profile, preferably using ``aiida-diff`` as the project name - that's it!
+        pip install -e .[docs]
 
+ #. Edit the individual documentation pages::
+
+        docs/source/index.rst
+        docs/source/developer_guide/index.rst
+        docs/source/user_guide/index.rst
+        docs/source/user_guide/get_started.rst
+        docs/source/user_guide/tutorial.rst
+
+ #. Use `Sphinx`_ to generate the html documentation::
+
+        cd docs
+        make
+
+Check the result by opening ``build/html/index.html`` in your browser.
+
+Publishing the documentation
+++++++++++++++++++++++++++++
+
+Once you're happy with your documentation, it's easy to host it online on ReadTheDocs_:
+
+ #. Create an account on ReadTheDocs_
+
+ #. Import your ``aiida-diff`` repository (preferably using ``aiida-diff`` as the project name)
+
+The documentation is now available at `aiida-diff.readthedocs.io <http://aiida-diff.readthedocs.io/>`_.
 
 PyPI release
 ++++++++++++
@@ -62,3 +86,11 @@ After this, you (and everyone else) should be able to::
 
 You can also enable *automatic* deployment of git tags to the python package index:
 simply generate a `PyPI API token <https://pypi.org/help/#apitoken>`_ for your PyPI account and add it as a secret to your GitHub repository under the name ``pypi_token`` (Go to Settings -> Secrets).
+
+.. note:: 
+
+   When updating the plugin package to a new version, remember to update the version number both in ``setup.json`` and ``aiida_diff/__init__.py``.
+
+
+.. _ReadTheDocs: https://readthedocs.org/
+.. _Sphinx: https://www.sphinx-doc.org/en/master/

setup.py

@@ -1,4 +1,4 @@
-from setuptools import setup, find_packages
+from setuptools import setup
 import json
 
 if __name__ == '__main__':
@@ -7,7 +7,7 @@
     with open('setup.json', 'r') as info:
         kwargs = json.load(info)
     setup(
-        packages=find_packages(),
+        packages=['aiida_diff'],
         # this doesn't work when placed in setup.json (something to do with str type)
         package_data={
             "": ["*"],