aiidateam · sphuber · Mar 2, 2019 · Mar 2, 2019 · Mar 2, 2019 · Mar 2, 2019
diff --git a/docs/Makefile b/docs/Makefile
@@ -22,6 +22,9 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 default:
 	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
+debug:
+	$(SPHINXBUILD) -b html -n $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
 all: html
 
 help:

diff --git a/docs/requirements_for_rtd.txt b/docs/requirements_for_rtd.txt
@@ -5,15 +5,15 @@ Flask-RESTful==0.3.6
 Flask-SQLAlchemy==2.3.2
 Flask==1.0.2
 Jinja2==2.10
-MarkupSafe==1.0
+MarkupSafe==1.1.1
 Pattern==2.6
 PyCifRW==4.2.1
 PyMySQL==0.8.0
 PyYAML==3.12
-Pygments==2.2.0
+Pygments==2.3.1
 SQLAlchemy-Utils==0.33.0
 SQLAlchemy==1.0.19
-Sphinx==1.7.4
+Sphinx==1.8.4
 aldjemy==0.8.0
 alembic==0.9.9
 amqp==1.4.9
@@ -61,7 +61,8 @@ seekpath==1.8.1
 singledispatch >= 3.4.0.3
 six==1.11.0
 spglib==1.10.3.65
-sphinx-rtd-theme==0.3.1
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-contentui==0.2.2
 sqlalchemy-diff==0.1.3
 sqlalchemy-migrate==0.11.0
 tabulate==0.8.2

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -44,7 +44,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive', 'sphinxcontrib.contentui']
 ipython_mplbackend = ""
 
 todo_include_todos = True
@@ -63,7 +63,7 @@
 
 # General information about the project.
 project = u'AiiDA'
-copyright = u'2016, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland and ROBERT BOSCH LLC, USA. All rights reserved'
+copyright = u'2019, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland and ROBERT BOSCH LLC, USA. All rights reserved'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

diff --git a/docs/source/get_started/index.rst b/docs/source/get_started/index.rst
@@ -1,4 +1,4 @@
-.. _get-started:
+.. _get_started:
 
 ===========
 Get started
@@ -581,3 +581,67 @@ database (the ``pk``, i.e. the principal key, and the ``uuid``).
   is raised) 
 
 And now, you are ready to launch your calculations!
+
+
+.. _plugins:
+
+#######
+Plugins
+#######
+
+AiiDA plug-ins are input generators and output parsers, enabling the
+integration of codes into AiiDA calculations and workflows.
+
+The plug-ins are not meant to completely automatize the calculation of physical properties. An underlying knowledge of how each code works, which flags it requires, etc. is still required. A total automatization, if desired, has to be implemented at the level of a workflow.
+
+Plugins live in different repositories than AiiDA.
+You can find a list of existing plugins on the `AiiDA website <http://www.aiida.net/plugins/>`_ or on the
+``aiida-registry`` (check the `JSON version <https://github.com/aiidateam/aiida-registry/blob/master/plugins.json>`_
+or the `human-readable version <https://aiidateam.github.io/aiida-registry/>`_), the official location to register
+and list plugins.
+
+
+Installing plugins
+++++++++++++++++++
+
+The plugins available for AiiDA are listed on the
+`AiiDA homepage <http://www.aiida.net/plugins/>`_
+
+For a plugin ``aiida-diff`` hosted on `PyPI <https://pypi.python.org/>`_,
+simply do::
+
+    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 directly from a source code repository, e.g.::
+
+    git clone https://github.com/aiidateam/aiida-diff
+    pip install aiida-diff
+    reentry scan -r aiida
+
+**Note:** Instead of updating the reentry cache via ``reentry scan -r aiida``,
+the same can be achieved from  python:
+
+.. code-block:: python
+
+    from reentry import manager
+    manager.scan(group_re='aiida')
+
+Background
++++++++++++
+
+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_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-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.
+
+For further details, see the Python `packaging user guide`_.
+
+.. _packaging user guide: https://packaging.python.org/distributing/#configuring-your-project
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,61 +14,31 @@ Welcome to AiiDA's documentation!
 
 AiiDA is a sophisticated framework designed from scratch to be a flexible and scalable infrastructure for computational science. Being able to store the full data provenance of each simulation, and based on a tailored database solution built for efficient data mining implementations, AiiDA gives the user the ability to interact seamlessly with any number of HPC machines and codes thanks to its flexible plugin interface, together with a powerful workflow engine for the automation of simulations.
 
-The software is available at http://www.aiida.net.
+ * Go through the :doc:`user's guide<user_guide/index>` to get started with AiiDA.
+ * Developers interested in adding new plugins or AiiDA internals, go to the :doc:`developer's guide<developer_guide/index>`.
+ * Use the complete :doc:`API reference<apidoc/aiida>`, the :ref:`modindex` or the :ref:`genindex` to find code you're looking for
 
-If you use AiiDA for your research, please cite the following work:
-
-.. highlights:: Giovanni Pizzi, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari,
-  and Boris Kozinsky, *AiiDA: automated interactive infrastructure and database 
-  for computational science*, Comp. Mat. Sci 111, 218-230 (2016);
-  http://dx.doi.org/10.1016/j.commatsci.2015.09.013; http://www.aiida.net.
-
-This is the documentation of the AiiDA framework. For the first setup, configuration and
-usage, refer to the :doc:`user's guide<user_guide/index>` below.
-
-If, instead, you plan to add new plugins, or you simply want to understand
-AiiDA internals, refer to the :doc:`developer's guide<developer_guide/index>`.
-
-User's guide
-++++++++++++
+For more resources on AiiDA, see http://www.aiida.net.
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 3
+   :hidden: 
 
    user_guide/index
-
-Other guide resources
-+++++++++++++++++++++
-
-.. toctree::
-   :maxdepth: 3
-
+   developer_guide/index
    other_guide/index
-
-
-Developer's guide
-+++++++++++++++++
-
-.. toctree::
-    :maxdepth: 3
-
-    developer_guide/index
-
-API reference
-+++++++++++++
-
-.. toctree::
-   :maxdepth: 4
-
    API reference <apidoc/aiida>
 
 
-Indices and tables
-==================
+How to cite
+===========
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+If you use AiiDA for your research, please cite the following work:
+
+.. highlights:: Giovanni Pizzi, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari,
+  and Boris Kozinsky, *AiiDA: automated interactive infrastructure and database 
+  for computational science*, Comp. Mat. Sci 111, 218-230 (2016);
+  http://dx.doi.org/10.1016/j.commatsci.2015.09.013; http://www.aiida.net.
 
 Acknowledgements
 ================

diff --git a/docs/source/installation/database.rst b/docs/source/installation/database.rst
diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst
@@ -7,11 +7,7 @@ Installation
 .. toctree::
 
   quick_install
-  plugins
-  optional_configuration
-  virtual_environment
-  database
-  verdi_setup
-  installation_requirements
+  prerequisites
+  installation
+  updating_installation
   troubleshooting
-  updating