From f1e99ed9355e0abb86083d948b92e947c36a8692 Mon Sep 17 00:00:00 2001 From: Fiona Naughton Date: Wed, 17 Jan 2024 08:14:08 -0800 Subject: [PATCH] fix formatting --- docs/source/reviewersguide.rst | 46 +++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/source/reviewersguide.rst b/docs/source/reviewersguide.rst index 1c291ad7..f39fc4f3 100644 --- a/docs/source/reviewersguide.rst +++ b/docs/source/reviewersguide.rst @@ -13,7 +13,7 @@ improvements to newer contributors. As such, your **aims of a reviewer** are to: #. Ensure the MDAKit can be *merged* (all necessary details *present* and *correct*), and #. Encourage *best practices* and *future work*. -| + This page provides a guide for reviewing an MDAKit submission, including a brief overview of the registration process and: @@ -70,19 +70,19 @@ On the PR - A failure on installing dependencies may be due the things in the Kit’s `pyproject.toml` not being properly defined -| + - **CHECK**: Did the docs build correctly? View the page generated by `readthedocs` (by clicking *Details* next to the check) and find the MDAKit’s entry on the Registry page. Check the expected information and badges are present on both the main list and the Kit’s individual page. -| + - **CHECK**: Is the metadata file named correctly and in the right location? The correct format is: `mdakits//metadata.yaml` (see `project_name`, below) -| + At the MDAKit’s Project Home ***************************** Follow the link to the project’s home provided in the metadata file and have a quick look at the MDAKit @@ -124,14 +124,14 @@ Entries *required* for registration - **CHECK**: This is a *string* and must match the name of the directory the `metadata.yaml` file is placed in. - **RECOMMEND**: It is suggested that this name also matches the host repository name. -| + `authors`: the ‘creators’ of the Kit - **CHECK**: This is a *list of strings*; either a list of names, or single entry with a link to an AUTHORS file at the project’s home. - **RECOMMEND**: An AUTHORS file is preferred (as this will be easier to update). -| + `maintainers`: the individuals responsible for the Kit going forward; they will be pinged if the MDAKit is failing @@ -140,34 +140,34 @@ is failing not obviously associated with the submission/project, ping them to check their agreement to be included. -| + `description`: a free form description of the Kit - **CHECK**: This is a *string*. Give the Kit a quick look - is the description reasonable? - **RECOMMEND**: Suggest anything you think would be useful to add to the Kit’s description. There’s no upper limit on length, but ideally ~1-3 sentences should be sufficient. -| + `keywords`: keywords that describe the Kit - **CHECK**: This is a *list of strings*. - **RECOMMEND**: Make any suggestions for things you think would be useful to add. See what keywords current MDAKits use for examples (note that keywords are case-insensitive when searching). -| + `licence`: the licence that the Kit falls under - **CHECK**: This is a *string*, which must be the SPDX ID of an `OSI approved licence `_. It should match the licence identified on the project’s home, e.g. in a LICENCE file. -| + `project_home`: a link to the Kit’s code - **CHECK**: This is a *string* and points to a reasonable location on a version-controlled repository e.g. GitHub, GitLab, BitBucket, etc. -| + `documentation_home`: a link to the Kit’s documentation - **CHECK**: This is a *string* and points somewhere sensible, which could be a single file (e.g. a @@ -176,7 +176,7 @@ is failing - **RECOMMEND**: While only basic documentation is required for registration, you can encourage the contributor to expand and improve their documentation in the future. -| + `documentation_type`: the type (i.e. “level of detail”) of documentation - **CHECK**: This is a *string* - e.g. 'README' (a basic overview), 'API' (description of the code) or @@ -185,7 +185,7 @@ is failing docs. If you judge that it does not, see if the submitter intends to continue working on these (and encourage them to do so!) -| + *Optional* entries ~~~~~~~~~~~~~~~~~~ @@ -198,18 +198,18 @@ CI is passing. - **RECOMMEND**: If the installation uses e.g. github or is otherwise complicated (many steps involved), 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*). -| + `python_requires`: range specifications for the versions of Python this Kit supports, e.g. “>=3.9”. This is a *string* (*AUTOMATIC CHECK*). -| + `mdanalysis_requires`: range specifications for the versions of MDAnalysis this Kit supports, e.g. “>=2.0.0”. This is a *string* (*AUTOMATIC CHECK*). @@ -219,7 +219,7 @@ is a *string* (*AUTOMATIC CHECK*). - **RECOMMEND**: Ideally, the Kit works with the current version of MDAnalysis - if an upper bound to an 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 @@ -229,29 +229,29 @@ is a *string* (*AUTOMATIC CHECK*). - **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*. -| + `development_status`: the development status of the MDAKit. - **CHECK**: This is a *string* and should match one of the `PyPI classifiers`_. - **RECOMMEND**: If you don’t think the provided status matches the actual state of the Kit’s code, you can query this - but don’t let it be a blocker. -| + `publications`: list of publications to be cited when using this MDAKit. - **CHECK**: This is a *list of strings*, and should include any relevant publications for the Kit itself as well as key upstream publications (e.g. if the Kit heavily relies on another package with an associated publication). -| + `changelog`: a link to the MDAKit’s changelog. - **CHECK**: This is a *string*. If included, check it points to a sensible place (e.g. a CHANGELOG