[WIP] Update documentation

docs/source/customising.rst

@@ -0,0 +1,72 @@
+.. _customising-label:
+
+Preparing and customising your project
+######################################
+Running the cookiecutter provides you with a skeleton for a Python package, 
+including configuration files for several optional tools.  All generated files 
+live in a the ``{repo_name}`` directory.
+
+The next steps are to add your code, corresponding tests and documentation, 
+and complete any extra steps to get optional tools running (e.g. linking to 
+external services). The sections below provide more detail on these steps. 
+Generated file will be discussed as the become relevant; see 
+:ref:`files-label` for an overview of all the generated files.
+
+.. toctree::
+   :maxdepth: 1
+
+   customising/github
+   customising/code
+   customising/tests
+   customising/documentation
+   customising/packaging
+
+
+In addition to code and configuration files, the cookiecutter template 
+includes several ready-to-go human-readable files intended to provide 
+information to your users, contributors, or general community. Make sure to 
+read each though and see that it matches your vision for your project, or 
+ammend appropriately:
+
+.. _general-info:
+
+* **License:** Your code needs to be clearly licensed so that users know if 
+  they can (legally) use it. The cookiecutter will apply the **GPLv2** 
+  license by default, included in the ``LICENSE`` file. If you decide to use a
+  different license (see `ChooseALicense <https://choosealicense.com/>`_), also 
+  update the copyright infromation in ``README.md``.
+
+* **README:** ``README.md`` is the introductory explanation to you project; it
+  will be rendered on your GitHub repo's home page. It has been pre-filled with 
+  some basic information, including your description and several badges that 
+  provide at-a-glance information to users on current version, test status, and more.
+
+.. _community-resources:
+
+**Community resources**
+
+* ``CODE_OF_CONDUCT.md`` outlines rules for behaviour for those in your community.
+* ``CONTRIBUTING.md`` provides information and instructions for those who want to contribute.
+
+
+
+Add your package to the MDAKit Registry!
+========================================
+The cookiecutter-generated template already ticks off most of the requirements
+for registering your MDAKit on the `MDAKit Registry <https://mdakits.mdanalysis.org/>`_!
+
+Once you've added your code, tests, and added the package to GitHub, you should
+be ready to start the `registration process <https://mdakits.mdanalysis.org/addingakit.html>`_
+(though it is recommended you continue to develop your package beyond these 
+basic requirements).
+
+.. _documenting-changes:
+
+Documenting changes going forward
+=================================
+An initial ``AUTHORS.md`` (pre-populated with your name)  and tempate 
+``CHANGELOG.md``  are also generated. As you go forward and develop your code, 
+**update these files to track all contributors and important changes to your 
+project**. Instructions are provided within each file suggesting the appropriate
+format to use.
+

docs/source/customising/code.rst

@@ -0,0 +1,68 @@
+Making and pushing changes to your code
+=======================================
+
+.. _adding-code:
+
+Now you should go forth and code!							
+
+Your project's code will live in the ``{package_name}/`` directory. 
+A basic ``__init__.py`` file (which :ref:`sets the version <versioning>`) as 
+been pre-generated, along with several subpackages (and accompanying (empty)
+``__init__.py``):
+
+* ``analysis/``: If you chose to include a template analysis class when 
+  running the cookiecutter, that class will appear in 
+  ``{package_name}/anaylsis/{template_analysis_class}.py``. This class is based 
+  on `MDAnalysis AnalysisBase <https://docs.mdanalysis.org/stable/documentation_pages/analysis/base.html>`_. 
+  Comments in file should help you as you customise this class for your analysis.						
+* ``tests/``: where your code's unit tests will live. See  :ref:`writing-tests`.
+
+* ``data/``: for including additional (non-code) files with your package, such 
+  as molecular structures; this may be useful for e.g. running tests. The 
+  included ``data/README.md`` file provides more information. ``files.py`` 
+  provides an example of how to set up files so they can be imported elsewhere
+  in your package (useful especially if you wish to use the data in multiple 
+  places), using the example datafile ``mda.txt``- containing ASCII art of the 
+  MDAnalysis logo. The :ref:`example test files <writing-tests>` include an 
+  example usage of this file.
+
+
+Tips while writing your code
+----------------------------
+To keep things clean and simple, we advise a few tips:
+
+.. _virtual-environment:
+
+* Always work in a virtual environment like ``conda``.
+  You can create a development environment by following
+  the instructions in the README. In short, to create an environment that should contain
+  all the tools you need to write and (locally) run tests and build documentation:
+
+
+  .. code-block:: bash
+
+    conda create --name <environment_name> python=3.8
+    conda activate <environment_name>  # remember to do this every time
+    conda env update --name <environment_name> --file devtools/conda-envs/test_env.yaml
+    conda env update --name <environment_name> --file docs/requirements.yaml
+
+
+* Always work in a separate branch. The ``main`` branch
+  is the default, or central, branch. All development
+  work should be done in a separate branch to avoid
+  messing up the main branch, or to allow you to work on
+  different approaches at the same time. This also
+  allows multiple people to work on the code at the same time.
+  Create a new branch with ``git checkout -b <my_branch_name>``.
+  See `GitHub's documentation on branches <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches>`_
+  for more information.
+
+* When you feel ready, open a pull request on GitHub.
+  **This does not have to be when you think you have finished the code!**
+  A PR runs tests and builds documentation.
+  This will allow others to review your code and
+  help you make sure it is correct.
+  It's always a good way to get feedback and validation,
+  as well as collaborate with other people.
+  See `GitHub's documentation on PRs <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
+  for more information.

docs/source/customising/documentation.rst

@@ -0,0 +1,142 @@
+.. _add-docs:
+
+Documentation
+=============
+Documentation is important for your users and for yourself.
+
+The documentation is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+Generally, a project will have a few types of documentation:
+
+* A ``README`` style overview, providing an quick introduction to the package
+  (or the subdirectory in which it is included) (a base-level ``README.md`` file 
+  is :ref:`automatically generated by the cookiecutter <general-info>`)
+
+* User guide-type documentation, which explains how and why to use the package.
+  While it may contain code examples, it's typically more of a broad
+  overview of package usage. 
+  For example, this page is user-guide-like documentation.
+  A stub page for user-guide-like documentation is created in
+  ``docs/source/getting_started.rst``.
+
+* API documentation, which explains how to use the code.
+  This is often automatically generated from docstrings in the code.
+  A stub page for API documentation is created in
+  ``docs/source/api.rst``.
+
+The template ``docs/`` directory contains configuration files and initial stub pages for generating User Guide and API documentation using `Sphinx <(https://www.sphinx-doc.org>`_.
+
+.. _documentation-writing:
+
+Writing documentation for Sphinx
+--------------------------------
+The cookiecutter creates three initial pages for your documentation, found in 
+``docs/source/``:
+
+* ``index.rst``: the 'home page', including a table of contents
+* ``getting_started.rst``: a stub page for user-guide-like documentation
+* ``api.rst``: a page for API documentation, using Sphinx's autosummary extension 
+  to automatically generate documentation from your code's docstrings, assumed to 
+  be `NumPy style docstrings <https://numpydoc.readthedocs.io/en/latest/format.html>`_
+
+These files are written in 
+`ReStructuredText format <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer>`_. 
+Modify these as you see fit, and add any additional pages in this folder. See the 
+`Sphinx User Guide <https://www.sphinx-doc.org/en/master/usage/index.html>`_ for help.
+
+.. _documentation-configuration:
+
+Configuring the documentation with Sphinx
+-----------------------------------------
+The documentation is configured in the ``docs/source/conf.py`` file.
+This file contains settings for the documentation, such as the
+project name, version, and theme. You can also add extensions
+to the documentation.
+More information on configuring Sphinx can be found in the
+`Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/configuration.html>`_.
+
+By default, the documentation is built using the MDAnalysis sphinx theme using 
+the default template MDAKits logo and `favicon`_, and includes 
+several useful extensions, e.g. to allow building of API docs from NumPy style docstrings.
+
+You can customise your documentation by:
+
+* **Add additional extensions and configuration options** - see the 
+  `Sphinx documentaiton <https://www.sphinx-doc.org/en/master/usage/configuration.html>`_.
+
+* **Changing the theme** by modifying the ``html_theme`` variable in
+  ``docs/source/conf.py``. You could also add custom style sheets in the 
+  ``docs/source/_static/`` and/or template pages in ``docs/source/_templates/``; 
+  see the respective ``README.md`` files in those folders for more information.
+
+* **Changing the logo**: You can also change the logo by either modifying the
+  ``html_logo`` variable or by replacing the ``_static/logo/mdakits-placeholder-logo.png`` 
+  file.
+  (This path is relative to the ``docs/source`` directory; the full path, relative 
+  to the repository root, is ``docs/source/_static/logo/mdakits-placeholder-logo.png``.)
+
+  Similarly, you can change the favicon by replacing the ``html_favicon`` 
+  variable or by replacing the ``_static/logo/mdakits-empty-favicon-template.svg`` file.
+
+  You are welcome to either create an entirely custom logo and favicon or to use 
+  the provided templates. An ``mdakits-empty-logo-template.svg`` and 
+  ``mdakits-empty-favicon-template.svg`` are provided in the
+  ``docs/source/_static/logo`` directory as templates for editing -- feel free to 
+  place your logo within the gears!
+
+
+.. _documentation-building:
+
+Building the documentation with Sphinx
+--------------------------------------
+Building documentation requires different dependencies to you main package;
+an initial list of dependencies is provided in ``docs/requirements.yaml`` which
+can be used to create a new virtual environment or 
+:ref:`be added to the current virtual environment <virtual-environment>`. 
+If you documentaiton requires additional/different dependencies, include them 
+here and in ``pyproject.toml``.
+
+The configuration file ``docs/Makefile`` and ``docs/make.bat`` are also provided
+to allow you to build your documentation.
+
+The documentation can be build by running the following command in the ``docs/`` directory:
+
+.. code-block:: bash
+
+  $ cd docs
+  $ make html
+
+This will build the documentation (as ``.html`` files) in a ``docs/_build/`` 
+directory; you can now view these files to see your built documention.
+
+
+.. _documentation-hosting:
+
+Hosting documentation with ReadTheDocs
+--------------------------------------
+
+If you selected the to 'include ReadTheDocs' when using the cookiecutter 
+(the default option), you can now use it to automatically build and host your 
+documentation.
+
+`ReadTheDocs <https://docs.readthdocs.io>`_ is an external service. To link it 
+to your repository, first log 
+in to ReadTheDocs using your GitHub account. Click ``Import a Project`` on the 
+ReadTheDocs dashboard (your project should appear here once it has pushed to GitHub).
+After importing you project, ReadTheDocs will build your documentation, 
+and it will now appear online with it's very own URL (likely at 
+``https://{repo_name}.readthedocs.io``)!
+
+We strongly recommend turning on building documentation for your
+pull requests to check and preview your docs. To do so:
+
+#. Go to the Admin tab
+#. Go to Advanced Settings
+#. Tick the "Build pull requests for this project" checkbox
+#. Scroll down and remember to click "Save"!
+
+A test build of the documentation will now be created and can be viewed for each PR.
+
+Further configuration can be done on from the ReadTheDocs dashboard or 
+in the ``readthedocs.yaml`` file - see the `ReadTheDocs documentation <https://docs.readthedocs.io/en/stable/config-file/v2.html>`_.
+

docs/source/customising/github.rst

@@ -0,0 +1,33 @@
+
+Adding the project to GitHub
+============================
+
+The generated ``{repo_name}`` directory should be an initialised git repository.
+We now need to connect it to GitHub:
+
+#. `Create a new repository on GitHub <https://docs.github.com/en/get-started/quickstart/create-a-repo>`_ .
+   **Do not** initialize the repo with a README, license, or any other files.
+#. Push the local repository to GitHub.
+   The `GitHub documentation <https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git>`_ should provide instructions for doing so, but in short:
+
+   * Add the remote named ``origin`` with :code:`git remote add origin <URL>`
+   * Push the local repository to the remote repository with :code:`git push -u origin main`
+   * Verify files were pushed successfully by checking on GitHub
+
+
+.. _github-features:
+
+**GitHub features**
+
+The ``.github/`` directory contains configuration files for useful features in 
+GitHub, including:
+
+* ``workflows/gh-ci.yaml`` for :ref:`running Continuous Integration <continuous-integration>`
+  using `GitHub Actions <https://docs.github.com/en/actions>`_. Other GitHub 
+  actions, e.g. for deployments, can be added to the ``workflows/`` directory.
+* ``.github/ISSUE_TEMPLATE/`` and ``.github/PULL_REQUEST_TEMPLATE.md`` provide 
+  templates that will be presented by GitHub to community members when making 
+  Issues and Pull Requests on your project's repository. They will help guide 
+  users/contributors to include all the relevant information, simplifying the 
+  process for both you and them.
+