making-a-kit overhaul

docs/source/addingakit.rst

@@ -0,0 +1,27 @@
+.. _add-mdakit:
+
+********************************
+Adding an MDAKit to the Registry
+********************************
+
+Do you have an MDAKit? Consider adding it to the `MDAKit registry`_!
+
+
+.. note::   
+   The `MDAKit registry`_ is still in its initial stages. We expect that the way in
+   which MDAKits are added, and the type of information required, may change
+   over time. Please reach out via the `issue tracker`_ if you have any
+   questions.
+
+**The registration process**
+
+Registering an MDAKit requires you to create a single file with metadata
+(called ``metadata.yaml``) describing the kit, and . You add this file to the `MDAnalysis/mdakits
+repository`_ on GitHub. Links below.
+
+.. toctree::
+   :maxdepth: 1
+
+   registering-a-kit/step-by-step
+   registering-a-kit/metadata-yaml
+

docs/source/index.rst

@@ -24,12 +24,19 @@ additional resources about MDAKits and how to write and/or add your own.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Resources
+   :caption: Resources for MDAKit Authors
 
-   about
    makingakit
-   add
+   addingakit
+   maintainingakit
    troubleshooting
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Other Resources
+
+   about
    reviewersguide
 
 

docs/source/maintainingakit.rst

@@ -0,0 +1,16 @@
+*********************
+Maintaining an MDAKit
+*********************
+
+* More TBA* 
+
+There are a variety of reasons a kit may behave unexpectedly after 
+being submitted to the registry.
+Apart from actively developing the kit, changes in kit dependencies, 
+or even Python itself, can introduce (deprecate) new (old) functionality.
+For this reason, the kits' continuous integration is rerun weekly to 
+confirm the kits expected behavior.
+
+In the event that a kit no longer passes its tests, an issue in MDAnalysis/MDAKits is automatically raised while notifying the maintainers indicated in the `metadata.yaml` file.
+While the registry developers will be happy to help where possible, ultimately, the maintainers of the MDAKit are responsible for resolving such issues and ensuring that the tests pass.
+The issue will automatically close after the next CI run if the tests pass again.

docs/source/making-a-kit/from-cookiecutter.rst

@@ -1,43 +1,47 @@
-************************************************
-Building from the cookiecutter: a guided example
-************************************************
+.. _guided-example:
+
+*********************************************
+Guided Example: Building an RMSF analysis Kit
+*********************************************
 
 In this section, we provide a guided example for creating an MDAKit
 using the `MDAKit cookiecutter <https://cookiecutter-mdakit.readthedocs.io>`_.
-A `video walk-through of this tutorial  <https://www.youtube.com/watch?v=viCPUHkgSxg>`_ 
-is available on YouTube.
+A `video walk-through <https://www.youtube.com/watch?v=viCPUHkgSxg>`_ 
+of this tutorial is available on YouTube.
 
 We will create a kit for RMSF analysis, replicating the functionality 
 of the `RMSF analysis class <https://docs.mdanalysis.org/stable/documentation_pages/analysis/rms.html#MDAnalysis.analysis.rms.RMSF>`_ 
 in the core library.
 
+First, let's refresh ourselves on the :ref:`requirements <requirements>` 
+for a 'registerable' kit. In brief:
 
 **MDAKit requirements**
 
-As a reminder, here are (in brief) the requirements (and recommendations)
-that we are aiming to fulfil to make a 'registerable' kit. See the 
-requirements in more detail :ref:`here <requirements>` 
-We'll check back in at the end of each part to see how we're going!
-
 #. Uses MDAnalysis
 #. Open source + OSI license
-#. Versioned + on a version-controlled repository
+#. Versioned + on version-controlled repository
 #. Designated authors and maintainers
 #. (At least) minimal documentation
 #. (At least) minimal regression tests
 #. Installable as a standard package
 #. (Recommended) community information available
-#. (Recommended) on a package distribution platform
+#. (Recommended) available on a package distribution platform
+
 
+Below are the steps we'll go through to create our MDAKit. We'll check
+back in after each part to see how we're proressing through these
+requirements!
 
 .. toctree::
    :maxdepth: 1
-   :caption: Steps
+   :caption: Steps for creating an MDAKit from the cookiecutter
 
    guided-example/use-cookiecutter
    guided-example/add-code
    guided-example/add-tests
    guided-example/to-github
    guided-example/add-docs
    guided-example/make-release
+   guided-example/registering
 

docs/source/making-a-kit/guided-example/add-code.rst

@@ -1,23 +1,23 @@
-***************************************************
-Part 2: Adding code to the newly created repository
-***************************************************
+*******************
+Part 2: Adding code
+*******************
 
 *For a video demonstration of this section,* 
-`click here  <https://www.youtube.com/watch?v=viCPUHkgSxg&t=48s>`_.
+`click here <https://www.youtube.com/watch?v=viCPUHkgSxg&t=48s>`_.
 
 Now that we have a shell for our MDAKit, we can begin to add our code
 to the ``rmsfkit/`` directory.
 
-In this example, we are recreating the exist MDAnalysis RMSD analysis,
-so we will simply copy and paste the analysis class into 
-``rmsfkit/rmsfkit.py``.The in-code documentation (which has been trimmed 
-here for brevity) is written in 
-`reStructuredText syntax <https://docutils.sourceforge.io/rst.html>`_
-syntax for building with Sphinx later. 
+#. In this example, we are recreating the existing MDAnalysis RMSF analysis,
+   so we will simply copy and paste this analysis class into a new file
+   ``rmsfkit/rmsfkit.py``.The in-code documentation (which has been trimmed 
+   here for brevity) is written in 
+   `reStructuredText syntax <https://docutils.sourceforge.io/rst.html>`_
+   for building with Sphinx later. 
 
-The contents of the file should now resemble the following code block:
+   The contents of the file should now resemble the following code block:
 
-.. code-block:: python
+   .. code-block:: python
 
 	"""
 	rmsfkit.py
@@ -101,18 +101,19 @@ The contents of the file should now resemble the following code block:
 	            raise ValueError("Some RMSF values negative; overflow " +
 	                             "or underflow occurred")
 
+#. Finally, to make our ``RMSF`` analysis class easier to access, we 
+   import it in ``__init__.py`` by adding:
 
-Finally, to make our ``RMSF`` analysis class easier to access, we 
-import it in ``__init__.py`` by adding:
-
-.. code-block:: python
+   .. code-block:: python
 
 	from .rmsfkit import RMSF
 
 
-**Progress: MDAKit requirements**
+Progress: MDAKit requirements
+-----------------------------
 
-#. **✓ Uses MDAnalysis**
+#. **✓ Uses MDAnalysis** - the added code uses the MDAnalysis
+   ``AnalysisBase`` class and runs on MDAnalysis ``AtomGroup`` objects!
 #. **✓ Open source + OSI license**
 #. *Versioned + on a version-controlled repository*
 #. **✓ Designated authors and maintainers**