new: standardisation (PR #22)

.github/SUPPORT.md

@@ -2,9 +2,14 @@
 
 ## Documentation
 - [Our API documentation](https://naturalhistorymuseum.github.io/dataportal-docs)
-- [CKAN documentation](http://docs.ckan.org/en/latest)
+- [Official CKAN documentation](http://docs.ckan.org/en/latest)
+
+## Issues
+- [The NHM on Github](https://github.com/NaturalHistoryMuseum)
+- [General issue tracker](https://github.com/NaturalHistoryMuseum/data-portal-issues/issues)
+- [Our CKAN extensions](https://github.com/search?q=topic%3Ackan+org%3ANaturalHistoryMuseum&type=repositories) (for more specific issues)
 
 ## Contact Us
 - [Gitter](https://gitter.im/nhm-data-portal/lobby)
 - [Email _data@nhm.ac.uk_](mailto:data@nhm.ac.uk)
-- [Twitter](https://twitter.com/nhm_data)
+- [Twitter](https://twitter.com/nhm_data)

.github/workflows/bump.yml

@@ -0,0 +1,31 @@
+name: Bump version
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  bump-version:
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    name: "Bump version and create changelog"
+    steps:
+      - name: Check out
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          fetch-depth: 0
+      - name: Create bump and changelog
+        uses: commitizen-tools/commitizen-action@master
+        with:
+          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          changelog_increment_filename: CURRENT.md
+          extra_requirements: "cz-nhm"
+      - name: Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body_path: "CURRENT.md"
+          tag_name: v${{ env.REVISION }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

.github/workflows/main.yml

@@ -6,20 +6,16 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
 
     steps:
       - name: Checkout source code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Build images
         run: docker-compose build
 
       - name: Run tests
-        run: docker-compose run ckan
-
-      - name: Run coveralls
         env:
-          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: docker-compose run -e COVERALLS_REPO_TOKEN ckan coveralls --service=github
-
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+        run: docker-compose run -e COVERALLS_REPO_TOKEN ckan bash /opt/scripts/run-tests.sh -c ckanext.contact

.github/workflows/pypi-publish.yml

@@ -0,0 +1,35 @@
+name: Upload Python Package
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip_existing: true

.gitignore

@@ -1,17 +1,9 @@
-# Compiled source #
-###################
-*.pyc
 *.egg-info
-
-# OS generated files #
-######################
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-.idea
-.coverage
+*.pyc
+.noseids
 .pytest_cache
+.coverage
+build/
+dist/
+.idea
+**/node_modules/

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: name-tests-test
+        args: ["--pytest-test-first"]
+        exclude: ^tests/helpers/
+      - id: trailing-whitespace
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v2.37.0
+    hooks:
+      - id: commitizen
+        additional_dependencies: ["cz-nhm"]
+  - repo: https://github.com/psf/black
+    rev: 22.10.0
+    hooks:
+      - id: black
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.5.0
+    hooks:
+      - id: docformatter
+        # these can't be pulled directly from the config atm, not sure why
+        args: ["-i", "--wrap-summaries=88", "--wrap-descriptions=88",
+               "--pre-summary-newline", "--make-summary-multi-line"]

.readthedocs.yaml

@@ -0,0 +1,8 @@
+version: 2
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+mkdocs:
+  configuration: mkdocs.yml

CHANGELOG.md

@@ -1,14 +1 @@
 # Changelog
-
-(This file may not be historically complete, as it is a recent addition to the project).
-
-## [1.1.0-alpha] - 2019-07-26
-
-- Merged in changes from master branch (which still runs on CKAN 2.3.0a) to enable reCAPTCHA
-
-## [1.0.0-alpha] - 2019-07-23
-
-- Updated to work with CKAN 2.9.0a, e.g.:
-    - uses toolkit wherever possible
-    - references to Pylons removed
-- Standardised README, CHANGELOG, setup.py and .github files to match other Museum extensions

LICENCE → LICENSE

@@ -1,7 +1,7 @@
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
- Copyright (C) 2016 Natural History Museum <http://nhm.ac.uk/>
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -631,8 +631,8 @@ to attach them to the start of each source file to most effectively
 state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
-    {one line to give the program's name and a brief idea of what it does.}
-    Copyright (C) {year}  {name of author}
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -645,14 +645,14 @@ the "copyright" line and a pointer to where the full notice is found.
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
   If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    {project}  Copyright (C) {year}  {fullname}
+    <program>  Copyright (C) <year>  <name of author>
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.
@@ -664,11 +664,11 @@ might be different; for a GUI interface, you would use an "about box".
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.
 
   The GNU General Public License does not permit incorporating your program
 into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -1,26 +1,32 @@
+<!--header-start-->
 <img src=".github/nhm-logo.svg" align="left" width="150px" height="100px" hspace="40"/>
 
 # ckanext-contact
 
-[![Tests](https://github.com/NaturalHistoryMuseum/ckanext-contact/actions/workflows/main.yml/badge.svg)](https://github.com/NaturalHistoryMuseum/ckanext-contact/actions/workflows/main.yml)
-[![Coveralls](https://img.shields.io/coveralls/github/NaturalHistoryMuseum/ckanext-contact/master.svg?style=flat-square)](https://coveralls.io/github/NaturalHistoryMuseum/ckanext-contact)
+[![Tests](https://img.shields.io/github/workflow/status/NaturalHistoryMuseum/ckanext-contact/Tests?style=flat-square)](https://github.com/NaturalHistoryMuseum/ckanext-contact/actions/workflows/main.yml)
+[![Coveralls](https://img.shields.io/coveralls/github/NaturalHistoryMuseum/ckanext-contact/main?style=flat-square)](https://coveralls.io/github/NaturalHistoryMuseum/ckanext-contact)
 [![CKAN](https://img.shields.io/badge/ckan-2.9.1-orange.svg?style=flat-square)](https://github.com/ckan/ckan)
 [![Python](https://img.shields.io/badge/python-3.6%20%7C%203.7%20%7C%203.8-blue.svg?style=flat-square)](https://www.python.org/)
+[![Docs](https://img.shields.io/readthedocs/ckanext-contact?style=flat-square)](https://ckanext-contact.readthedocs.io)
 
 _A CKAN extension for adding popup contact forms to pages._
 
+<!--header-end-->
 
 # Overview
 
+<!--overview-start-->
 Borrows much of the contact form code from [ckanext-surrey](https://github.com/CityofSurrey/ckanext-surrey).
 
 An example can be seen on the Natural History Museum's [Data Portal](https://data.nhm.ac.uk) when clicking "_Contact dataset curator._"
 
 This extension now includes Google's [reCAPTCHA](https://www.google.com/recaptcha) for preventing spam submissions.
 
+<!--overview-end-->
 
 # Installation
 
+<!--installation-start-->
 Path variables used below:
 - `$INSTALL_FOLDER` (i.e. where CKAN is installed), e.g. `/usr/lib/ckan/default`
 - `$CONFIG_FILE`, e.g. `/etc/ckan/default/development.ini`
@@ -58,10 +64,14 @@ Path variables used below:
   ckan.plugins = ... contact
   ```
 
+6. To use reCAPTCHA, you must register a site with the Google [reCAPTCHA](https://www.google.com/recaptcha) service and add your API key and secret in the [configuration](#configuration).
+
+<!--installation-end-->
 
 # Configuration
 
-There are no settings that _must_ be provided in your .ini config file, but there are some options:
+<!--configuration-start-->
+These are the options that can be specified in your .ini config file.
 
 ## Email
 
@@ -80,13 +90,11 @@ Name|Description|Default
 `ckanext.contact.recaptcha_v3_secret`|API secret for the reCAPTCHA service.|False (i.e. disabled)
 `ckanext.contact.recaptcha_v3_action`|`data-module-action` for the form/button|
 
-
-# Further Setup
-
-To use reCAPTCHA, you must register a site with the Google [reCAPTCHA](https://www.google.com/recaptcha) service and add your API key and secret in the [configuration](#configuration).
+<!--configuration-end-->
 
 # Usage
 
+<!--usage-start-->
 Add the following HTML where you want the contact button to appear:
 
 ```html+jinja
@@ -101,12 +109,12 @@ Add the following HTML where you want the contact button to appear:
 
 Where `params` is a dict with three entries: package_id, resource_id, record_id (all of which are optional).
 
+<!--usage-end-->
 
 # Testing
-_Test coverage is currently extremely limited._
 
-To run the tests in this extension, there is a Docker compose configuration available in this
-repository to make it easy.
+<!--testing-start-->
+There is a Docker compose configuration available in this repository to make it easier to run tests.
 
 To run the tests against ckan 2.9.x on Python3:
 
@@ -123,4 +131,6 @@ docker-compose build
 docker-compose run ckan
 ```
 
-The ckan image uses the Dockerfile in the `docker/` folder which is based on `openknowledge/ckan-dev:2.9`
+The ckan image uses the Dockerfile in the `docker/` folder.
+
+<!--testing-end-->

ckanext/__init__.py

@@ -6,7 +6,9 @@
 
 try:
     import pkg_resources
+
     pkg_resources.declare_namespace(__name__)
 except ImportError:
     import pkgutil
+
     __path__ = pkgutil.extend_path(__path__, __name__)

ckanext/contact/__init__.py

@@ -6,7 +6,9 @@
 
 try:
     import pkg_resources
+
     pkg_resources.declare_namespace(__name__)
 except ImportError:
     import pkgutil
+
     __path__ = pkgutil.extend_path(__path__, __name__)

ckanext/contact/auth.py

@@ -9,12 +9,10 @@
 
 @toolkit.auth_allow_anonymous_access
 def send_contact(context, data_dict):
-    '''
+    """
     Auth for sending the contact form, always returns true.
 
     :param context:
     :param data_dict:
-    '''
-    return {
-        'success': True
-    }
+    """
+    return {'success': True}

ckanext/contact/interfaces.py

@@ -8,15 +8,17 @@
 
 
 class IContact(interfaces.Interface):
-    '''Hook into contact form'''
+    """
+    Hook into contact form.
+    """
 
     def mail_alter(self, mail_dict, data_dict):
-        '''Allow altering of email values
-        For example, allow directing contact form dependent on form values
+        """
+        Allow altering of email values For example, allow directing contact form
+        dependent on form values.
 
         :param data_dict: form values
         :param mail_dict: dictionary of mail values, used in mailer.mail_recipient
         :returns: altered mail_dict
-
-        '''
+        """
         return mail_dict