diff --git a/README.rst b/README.rst index 4cf23ed6..a6e725bf 100644 --- a/README.rst +++ b/README.rst @@ -37,19 +37,6 @@ this repository and adding a new `metadata`_ file within it's own respective directory under `mdakits`. -Workflow -======== - -Shown below is the MDAKit framework workflow. - - -.. image:: https://github.com/MDAnalysis/MDAKits/blob/main/assets/MDAKitFramework.png - :alt: The MDAKit Framework - :align: center - - -For more details see the `MDAKit Whitepaper`_. - License ======= diff --git a/docs/source/about.rst b/docs/source/about.rst index afdc4b55..db5dc7c2 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -27,11 +27,12 @@ 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 It is also highly encouraged that the MDAKit also satisfies: -#. The code is installable as a standard package #. Information on bug reporting, user discussions, and community guidelines is made available +#. The code is made available on a package distribution platform (e.g. PyPi or conda-forge). Registered MDAKits are then `listed here`_ with the intention of providing a centralised place where the community can find out more about them. Where possible, the MDAKits are diff --git a/docs/source/makingakit.rst b/docs/source/makingakit.rst index e8808d63..9bdced09 100644 --- a/docs/source/makingakit.rst +++ b/docs/source/makingakit.rst @@ -15,11 +15,12 @@ In order to be accepted, there are several :ref:`requirements ` th #. 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 source code is installable as a standard package It is also highly encouraged that the MDAKit also satisfies: -#. Code is installable as a standard package #. Information on bug reporting, user discussions, and community guidelines is made available +#. The code is made available on a package distribution platform (e.g. PyPi or conda-forge). These requirements ensure that registered packages are FAIR-compliant and hold up to an ideal scientific standard. Without prior experience, some of the requirements listed above can be daunting. @@ -31,7 +32,7 @@ Building from the cookiecutter The MDAKits cookiecutter template (using the `Cookiecutter tool `_) can be used to rapidly develop a FAIR-compliant MDAKit by generating placeholder code for documentation, testing, and installation. While its usage is outlined in detail in the `MDAKit cookiecutter `_ documentation, here we provide a full walk-through for creating an RMSF analysis kit, recreating the functionality of the `RMSF analysis class `_ in the core library. -Starting from an environment with Python 3.9+ and the `Cookiecutter tool `_, the MDAKit template is generated using +Starting from an environment with Python 3.10+ and the `Cookiecutter tool `_, the MDAKit template is generated using .. code-block:: @@ -639,13 +640,13 @@ The contents of ``metadata.yaml`` for ``rmsfkit`` are: license: GPL-2.0-or-later project_home: https://github.com/yourusername/rmsfkit documentation_home: https://rmsfkit.readthedocs.io/en/latest/ - documentation_type: API + documentation_type: API + src_install: + - git clone https://github.com/yourusername/rmsfkit.git + - cd rmsfkit/ + - pip install . ## Optional entries - src_install: - - git clone https://github.com/yourusername/rmsfkit.git - - cd rmsfkit/ - - pip install . python_requires: ">=3.9" mdanalysis_requires: ">=2.0.0" run_tests: diff --git a/docs/source/reviewersguide.rst b/docs/source/reviewersguide.rst index cd1de32f..6b7c3165 100644 --- a/docs/source/reviewersguide.rst +++ b/docs/source/reviewersguide.rst @@ -190,6 +190,24 @@ is failing encourage them to do so!) +``src_install``: a list of commands to install the Kit from the source code. This is a *list of strings* +(*AUTOMATIC CHECK*). + + +``run_tests``: a list of commands to run the Kit’s tests. This is a *list of strings* (*AUTOMATIC CHECK*). + +- *note*: while (minimal) tests are one of the requirements of an MDAKit, we recognize that there might + be testing frameworks that we do not support yet. In those cases please exercise flexibility when + reviewing. +- **RECOMMEND**: While a MDAKit may be registered with only minimal tests, encourage the contributor + to continue improving their tests in the future. + + +``test_dependencies``: a list of commands for installing any dependencies required by the MDAKit’s tests. +This is a *list of strings* (*AUTOMATIC CHECK*). + + + *Optional* entries ~~~~~~~~~~~~~~~~~~ @@ -203,10 +221,6 @@ CI is passing. encourage the contributor to make a release on conda-forge or PyPI. -``src_install``: a list of commands to install the Kit from the source code. This is a *list of strings* -(*AUTOMATIC CHECK*). - - ``import_name``: the package name, used to import the Kit in Python. This is a *string* (*AUTOMATIC CHECK*). @@ -224,20 +238,6 @@ is a *string* (*AUTOMATIC CHECK*). old version is given, enquire why, and recommend updating the Kit to work with a current version. -``run_tests``: a list of commands to run the Kit’s tests. This is a *list of strings* (*AUTOMATIC CHECK*). - -- *note*: while (minimal) tests are one of the requirements of an MDAKit, providing instructions on how to run - tests in the metadata file is currently optional, in order to allow greater flexibility in - what format tests take and so lower the entry barrier for new contributors. However, it is *highly - recommended* here to provide this metadata. -- **RECOMMEND**: While a MDAKit may be registered with only minimal tests, encourage the contributor - to continue improving their tests in the future. - - -``test_dependencies``: a list of commands for installing any dependencies required by the MDAKit’s tests. -This is a *list of strings* (*AUTOMATIC CHECK*). - - ``project_org``: the account under which the code is found - this may be an individual user account, or an organisation like MDAnalysis. This is a *string*. diff --git a/mdakits/template/metadata.yaml b/mdakits/template/metadata.yaml index 0f490efe..9e61a56e 100644 --- a/mdakits/template/metadata.yaml +++ b/mdakits/template/metadata.yaml @@ -52,18 +52,6 @@ documentation_home: https://MYPROJECT.readthedocs.io ## str: the type of documentation available [UserGuide, API, README] documentation_type: UserGuide + API -#------------------------------------------------------------ -# Optional entries -#------------------------------------------------------------ -## List(str): a list of commands to use when installing the latest -## release of the code. Note: only one installation method can currently -## be defined. We suggest using mamba where possible (e.g. -## mamba -c conda-forge install MYPROJECT -## for a conda package installation). -## Here we use a simple PyPi installation: -install: - - pip install MYPROJECT - ## List(str): a list of commands to use when installing the mdakit from its ## source code. src_install: @@ -102,6 +90,18 @@ test_dependencies: ## str: the organisation name the MDAKit falls under project_org: GH_HOST_ACCOUNT +#------------------------------------------------------------ +# Optional entries +#------------------------------------------------------------ +## List(str): a list of commands to use when installing the latest +## release of the code. Note: only one installation method can currently +## be defined. We suggest using mamba where possible (e.g. +## mamba -c conda-forge install MYPROJECT +## for a conda package installation). +## Here we use a simple PyPi installation: +install: + - pip install MYPROJECT + ## str: the development status of the MDAKit ## See https://pypi.org/classifiers/ for development status classifiers. development_status: Production/Stable