From 107ada87ba0b1688161263955d2a39c11150c698 Mon Sep 17 00:00:00 2001 From: Leopold Talirz Date: Fri, 24 Aug 2018 22:43:19 +0200 Subject: [PATCH] plugin dev docs: migrate to plugin cutter (#1904) migrating from outdated aiida-plugin-template to more comfortable plugin cutter. --- .../developer_guide/plugins/documenting.rst | 43 ++++++------------- .../developer_guide/plugins/quickstart.rst | 20 +++------ docs/source/installation/plugins.rst | 16 +++---- 3 files changed, 29 insertions(+), 50 deletions(-) diff --git a/docs/source/developer_guide/plugins/documenting.rst b/docs/source/developer_guide/plugins/documenting.rst index 56185b5094..8070c3f015 100644 --- a/docs/source/developer_guide/plugins/documenting.rst +++ b/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/ diff --git a/docs/source/developer_guide/plugins/quickstart.rst b/docs/source/developer_guide/plugins/quickstart.rst index 0f787fd709..a57f163986 100644 --- a/docs/source/developer_guide/plugins/quickstart.rst +++ b/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 ` to make sure this works. 1. Check on the `aiida plugin 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 `_ 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 # 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 diff --git a/docs/source/installation/plugins.rst b/docs/source/installation/plugins.rst index 96aa20af12..633cf9eb07 100644 --- a/docs/source/installation/plugins.rst +++ b/docs/source/installation/plugins.rst @@ -7,28 +7,28 @@ Installing plugins The plugins available for AiiDA are listed on the `AiiDA homepage `_ -For a plugin ``aiida-plugin-template`` hosted on -`PyPI `_, simply do:: +For a plugin ``aiida-diff`` hosted on `PyPI `_, +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.