plugin dev docs: migrate to plugin cutter (#1904)

migrating from outdated aiida-plugin-template to more comfortable
plugin cutter.

docs/source/developer_guide/plugins/documenting.rst

@@ -2,51 +2,36 @@
 Documenting a plugin
 ====================
 
-The `aiida plugin template`_ already comes with a template for documentation
-that just needs to be adjusted to your needs.
-In the following we, again, assume you wrote a plugin named ``aiida-compute``:
+If you used the `AiiDA plugin cutter`_,  your plugin already comes with a basic
+documentation that just needs to be adjusted to your needs.
 
- #. Modify ``docs/source/conf.py`` template configuration file inserting the information about your plugin:
+ #. Install the ``docs`` extra::
 
-        - Replace ``aiida_plugin_template`` by ``aiida_compute``
+        pip install -e .[docs]
 
-        - Replace ``aiida-plugin-template`` by ``aiida-compute``
-
-        - Modify ``intersphinx_mapping`` adding any other packages that are needed by your plugin
-
-        - Update general information about the project::
-
-                project = u'aiida-compute'
-                copyright_first_year = 2017
-                copyright_owners = "My Institution, Country"
-
- #. Populate or delete the individual documentation pages::
-
-        docs/source/module_guide/calculations.rst
-        docs/source/module_guide/data.rst
-        docs/source/module_guide/parsers.rst
-        docs/source/user_guide/get_started.rst
-        docs/source/user_guide/tutorial.rst
-
- #. Update the indices accordingly::
+ #. Populate, delete, or add to the individual documentation pages::
 
+        docs/source/index.rst
         docs/source/module_guide/index.rst
         docs/source/user_guide/index.rst
+        docs/source/user_guide/get_started.rst
+        docs/source/user_guide/tutorial.rst
     
- #. Make sure that AiiDA docs dependencies ``sphinx`` and ``sphinx_rtd_theme`` are installed
-
- #. Generate the html documentation via sphinx::
+ #. Use `Sphinx`_ to generate the html documentation::
 
         cd docs
         make
 
+    Check the result by opening ``build/html/index.html`` in your browser.
+
  #. Host your documentation online on ReadTheDocs_.
     Simply sign up and import your project.  Make sure to add the path to the
     requirements file ``docs/requirements_for_rtd.txt`` and the Python
     configuration file ``docs/source/conf.py`` in Admin => Advanced settings.
 
 Note: When updating the plugin to a new version, remember to update the
-version number both in ``setup.json`` and ``aiida_compute/__init__.py``.
+version number both in ``setup.json`` and ``aiida_mycode/__init__.py``.
 
-.. _aiida plugin template: https://github.com/aiidateam/aiida-plugin-template
+.. _aiida plugin cutter: https://github.com/aiidateam/aiida-plugin-cutter
 .. _ReadTheDocs: http://readthedocs.org/
+.. _sphinx: http://www.sphinx-doc.org/en/master/

docs/source/developer_guide/plugins/quickstart.rst

@@ -11,28 +11,22 @@ Let's get started with creating a new plugin ``aiida-mycode``.
  0. At least once, :ref:`install an existing aiida plugin <plugins>` to make sure this works.
 
  1. Check on the `aiida plugin registry <https://aiidateam.github.io/aiida-registry/>`_
-    that the plugin name is still available
+    that your desired plugin name is still available
 
- #. Download the AiiDA plugin template::
+ #. Use the `AiiDA plugin cutter <https://github.com/aiidateam/aiida-plugin-cutter>`_ to jumpstart your plugin::
 
-        wget https://github.com/aiidateam/aiida-plugin-template/archive/master.zip
-        unzip master.zip
-        cd aiida-plugin-template
+        pip install cookiecutter
+        cookiecutter https://github.com/aiidateam/aiida-plugin-cutter.git
+        # follow instructions ...
+        cd aiida-mycode
 
- #. Replace the name ``aiida-plugin-template`` by ``aiida-mycode``::
-
-        mv aiida_plugin_template aiida_mycode
-        sed -i .bak 's/aiida_plugin_template/aiida_mycode/g' README.md setup.json examples/*.py
-        sed -i .bak 's/aiida-plugin-template/aiida-mycode/g' README.md setup.json
-        sed -i .bak 's/template\./mycode./g' setup.json
  #. Install your new plugin::
 
         workon <name_of_your_virtualenv> # if you have one
         pip install -e .
         reentry scan -r aiida
 
-That's it - now you can ``import aiida-mycode`` and start developing your plugin
-
+That's it - now you can ``import aiida_mycode`` and start developing your plugin
 
 A few things to keep in mind:
  * Be sure to update the `setup.json`_, in particular the license and version number

docs/source/installation/plugins.rst

@@ -7,28 +7,28 @@ Installing plugins
 The plugins available for AiiDA are listed on the
 `AiiDA homepage <http://www.aiida.net/plugins/>`_
 
-For a plugin ``aiida-plugin-template`` hosted on 
-`PyPI <https://pypi.python.org/>`_, simply do::
+For a plugin ``aiida-diff`` hosted on `PyPI <https://pypi.python.org/>`_,
+simply do::
 
-    pip install aiida-plugin-template
+    pip install aiida-diff
     reentry scan -r aiida   # notify aiida of new entry points
 
 In case there is no PyPI package available, you can install 
 the plugin from the python source, e.g.::
 
-    git clone https://github.com/aiidateam/aiida-plugin-template
-    pip install aiida-plugin-template
+    git clone https://github.com/aiidateam/aiida-diff
+    pip install aiida-diff
     reentry scan -r aiida
 
 Background
 -----------
 
-What does ``pip install aiida-plugin-template`` do?
+What does ``pip install aiida-diff`` do?
 
 * resolves and installs the dependencies on other python packages as specified in ``setup.py``
-* creates a folder ``aiida_plugin_template.egg-info/`` with metadata about the package
+* creates a folder ``aiida_diff.egg-info/`` with metadata about the package
 * if the ``-e`` option is given, creates a symbolic link from the python package
-  search path to the ``aiida-plugin-template`` directory
+  search path to the ``aiida-diff`` directory
   and puts the ``.egg-info`` folder there.
   Changes to the **source code** will be picked up by python without reinstalling, 
   but changes to the **metadata** in ``setup.json`` will not.