Splitting the tutorial (#173)

* fix  #156 (split making tutorial into sub pages)
* fix #86 (embed video)
* update notes on versioning: we switched the cookiecutter from versioneer to versioningit

docs/requirements.yaml

@@ -9,6 +9,7 @@ dependencies:
 
     - sphinx
     - mdanalysis-sphinx-theme
+    - sphinxcontrib-youtube
 
     - pyyaml
     - pydantic

docs/source/about.rst

@@ -1,5 +1,7 @@
 .. -*- coding: utf-8 -*-
 
+.. _about-mdakits:
+
 *************
 About MDAKits
 *************
@@ -27,7 +29,7 @@ requirements**:
 #. Minimal documentation is provided (what your code does, how to install it,
    and how to use it)
 #. At least minimal regression tests are present; continuous integration is encouraged
-#. The code is installable as a standard package
+#. The source code is installable as a standard package
 
 It is also highly encouraged that the MDAKit also satisfies:
 

docs/source/addingakit.rst

@@ -0,0 +1,34 @@
+.. _add-mdakit:
+
+********************************
+Adding an MDAKit to the Registry
+********************************
+
+Do you have an MDAKit? Consider adding it to the 
+:ref:`MDAKits Registry! <mdakits>`.
+
+.. 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.
+
+Registering an MDAKit requires you to create a single file with meta information
+(called ``metadata.yaml``) describing the Kit, and add this to the 
+`MDAnalysis/mdakits repository`_ on GitHub. The links below provide information
+about this process and more detail about the ``metadata.yaml`` file.
+
+.. toctree::
+   :maxdepth: 2
+
+   registering-a-kit/step-by-step
+   registering-a-kit/metadata-yaml
+
+
+.. _`MDAKit registry`: https://mdakits.mdanalysis.org/mdakits.html
+
+.. _`issue tracker`:
+   https://github.com/MDAnalysis/MDAKits/issues
+
+.. _`MDAnalysis/mdakits repository`:
+   https://github.com/MDAnalysis/mdakits

docs/source/conf.py

@@ -56,6 +56,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinxcontrib.youtube',
 ]
 
 autosummary_generate = True

docs/source/index.rst

@@ -11,8 +11,11 @@ Welcome to the MDAKit registry!
 Showcased here are a list of community generated packages which extend the
 functionality of the `MDAnalysis library`_.
 
-Follow the links below to begin exploring the available MDAKits, or view
-additional resources about MDAKits and how to write and/or add your own.
+For more information about MDAKits and the motivation behind them, please see 
+the :ref:`about-mdakits` page. 
+
+To begin exploring the :ref:`available MDAKits <mdakits>`, or view additional 
+resources on MDAKits and how to write and/or add your own, follow the links below!
 
 
 .. toctree::
@@ -24,12 +27,25 @@ additional resources about MDAKits and how to write and/or add your own.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Resources
+   :caption: About
 
    about
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Resources for MDAKit Authors
+
    makingakit
-   add
+   addingakit
+   maintainingakit
    troubleshooting
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Other Resources
+
    reviewersguide
 
 

docs/source/maintainingakit.rst

@@ -0,0 +1,27 @@
+.. _maintaining:
+
+*********************
+Maintaining an MDAKit
+*********************
+
+.. note::   
+   This section is still under construction. If you have topics you would
+   like to see covered here, please get in touch via 
+   `MDAnalysis Github Discussion`_.
+
+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.
+
+.. _`MDAnalysis GitHub Discussions`:
+   https://github.com/MDAnalysis/mdanalysis/discussions

docs/source/making-a-kit/documentation.rst

@@ -0,0 +1,24 @@
+.. _documentation:
+
+*************
+Documentation
+*************
+
+Basic documentation is **required** for MDAKit registration. The detail and 
+depth of the documentation is ultimately up to you, but we require **at a 
+minimum** that you provide README-style documentation explaining what the code
+is supposed to do, how to install it, and the basics of its use.
+
+Although this is the minimum, we highly recommend that you consider generating
+your documentation with dedicated tools such as 
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_, which allows you to generate
+static documentation using 
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+-formatted plain text directly from your code. This makes it easier for your
+documentation to change alongside code changes.
+
+Using a **documentation hosting service** such as 
+`Read the Docs <https://readthedocs.org>`_ or 
+`GitHub Pages <https://pages.github.com/>`_ allows easy public access to your
+automatically generated documentation.
+

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

@@ -0,0 +1,51 @@
+.. _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 <https://www.youtube.com/watch?v=viCPUHkgSxg>`_ 
+of this tutorial is available on YouTube:
+
+.. youtube:: viCPUHkgSxg
+   :align: center
+
+
+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**
+
+#. Uses MDAnalysis
+#. Open source + OSI license
+#. Versioned + on a 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) 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 progressing through these
+requirements!
+
+.. toctree::
+   :maxdepth: 1
+   :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
+