From f32436c82afa40390e5a30d7514e547484f332a7 Mon Sep 17 00:00:00 2001 From: Jonathan Nichols Date: Tue, 25 Jun 2024 16:57:15 +0100 Subject: [PATCH] Convert readme format --- MANIFEST.in | 1 - README.md | 84 +++++++++++++++++++++++++++++++++++++++++ README.rst | 105 ---------------------------------------------------- setup.py | 2 +- 4 files changed, 85 insertions(+), 107 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/MANIFEST.in b/MANIFEST.in index fc0e02e4..a5b2da08 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1 @@ -include README.rst recursive-include ckanext/datagovuk *.html *.json *.js *.less *.css *.mo \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..64117de6 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# ckanext-datagovuk + +The CKAN extension for data.gov.uk + +## Features + +- Configures Sentry automatically using a `SENTRY_DSN` environment variable. + +## Installation + +To install ckanext-datagovuk: + +1. Activate your CKAN virtual environment, for example: + +``` +/usr/lib/ckan/default/bin/activate +``` + +1. Install the ckanext-datagovuk Python package into your virtual environment: + +``` +pip install ckanext-datagovuk +``` + +1. Add `datagovuk` to the `ckan.plugins` setting in your CKAN config file (by default the config file is located at `/etc/ckan/default/production.ini`). + +1. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu: + +``` +sudo service apache2 reload +``` + +## Config Settings + +`ckan.datagovuk.trim_strings_for_index_limit`: when indexing packages, string fields will be truncated to this length unless they are known to be under a text-indexed key. Solr 6 has a field limit of 32k for string fields, but note that our truncation is applied per-json-value, and a Solr value can contain multiple json values which then get squashed together to a single field value, so using a number under half Solr's limit is wise. + +## Development Installation + +To install ckanext-datagovuk for development, activate your CKAN virtualenv and +then: + +``` +git clone https://github.com/alphagov/ckanext-datagovuk.git +cd ckanext-datagovuk +python setup.py develop +pip install -r dev-requirements.txt +``` + +## Running the Tests + +Start by running the [docker ckan](https://github.com/alphagov/docker-ckan#development-mode) stack to set up the CKAN environment. + +Run the tests: + +``` +python -m pytest --ckan-ini=test.ini ckanext/datagovuk/tests/ +``` + +## Creating test data + +To be able to run the [CKAN functional tests](https://github.com/alphagov/ckan-functional-tests) we need to create test data. + +First set the environment variables: + +- `CKAN_INI` - location of CKAN ini file, this is already set on the docker stack +- `CKAN_TEST_SYSADMIN_NAME` and `CKAN_TEST_SYSADMIN_PASSWORD` + +Then run the paster command: + +``` +ckan datagovuk create-dgu-test-data +``` + +To remove the test data: + +``` +ckan datagovuk remove-dgu-test-data +``` + +## Deploying CKAN, PyCSW and Solr + +By default, merging a PR into main will trigger a build of the CKAN image and create PRs on the govuk-dgu-charts repo. Updating the tag will build and push a tagged image and create the PR for Staging and Production environments in the govuk-dgu-charts repo. + +If you want to deploy updates to PyCSW or Solr then you'll need to trigger the build manually via the github actions tab and manually update the pycsw or solr tag in govuk-dgu-charts repo for each environment. diff --git a/README.rst b/README.rst deleted file mode 100644 index f9053cdf..00000000 --- a/README.rst +++ /dev/null @@ -1,105 +0,0 @@ - -============= -ckanext-datagovuk -============= - -.. Put a description of your extension here: - What does it do? What features does it have? - Consider including some screenshots or embedding a video! - --------- -Features --------- - -- Configures Sentry automatically using a `SENTRY_DSN` environment variable. - ------------- -Installation ------------- - -.. Add any additional install steps to the list below. - For example installing any non-Python dependencies or adding any required - config settings. - -To install ckanext-datagovuk: - -1. Activate your CKAN virtual environment, for example:: - - . /usr/lib/ckan/default/bin/activate - -2. Install the ckanext-datagovuk Python package into your virtual environment:: - - pip install ckanext-datagovuk - -3. Add ``datagovuk`` to the ``ckan.plugins`` setting in your CKAN - config file (by default the config file is located at - ``/etc/ckan/default/production.ini``). - -4. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:: - - sudo service apache2 reload - - ---------------- -Config Settings ---------------- - -Document any optional config settings here. - - - ``ckan.datagovuk.trim_strings_for_index_limit``: when indexing packages, string - fields will be truncated to this length unless they are known to be under a - text-indexed key. Solr 6 has a field limit of 32k for string fields, but note - that our truncation is applied per-json-value, and a Solr value can contain - multiple json values which then get squashed together to a single field value, - so using a number under half Solr's limit is wise. - - ------------------------- -Development Installation ------------------------- - -To install ckanext-datagovuk for development, activate your CKAN virtualenv and -do:: - - git clone https://github.com/alphagov/ckanext-datagovuk.git - cd ckanext-datagovuk - python setup.py develop - pip install -r dev-requirements.txt - - ------------------ -Running the Tests ------------------ - -Start by running the `docker ckan `_ stack so that the CKAN environment is set up. - -Run the tests, do:: - - python -m pytest --ckan-ini=test.ini ckanext/datagovuk/tests/ - ------------------ -Creating test data ------------------ - -In order to be able to run the `CKAN functional tests `_ -we need to create test data. - -Before running the paster command set the environment varibales: -- CKAN_INI - location of CKAN ini file, this is already set on the docker stack -- CKAN_TEST_SYSADMIN_NAME and CKAN_TEST_SYSADMIN_PASSWORD - -Then run the paster command: - - ckan datagovuk create-dgu-test-data - -In order to remove the test data: - - ckan datagovuk remove-dgu-test-data - ------------------ -Deploying CKAN, PyCSW and Solr ------------------ - -By default merging a PR into main will trigger a build of the CKAN image and create PRs on the govuk-dgu-charts repo. Updating the tag will build and push a tagged image and create the PR for Staging and Production environments in the govuk-dgu-charts repo. - -If you want to deploy updates to PyCSW or Solr then you will need to trigger the build manually via the github actions tab and manually update the pycsw or solr tag in govuk-dgu-charts repo for each environment. diff --git a/setup.py b/setup.py index 338ddd80..f028db54 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ here = path.abspath(path.dirname(__file__)) # Get the long description from the relevant file -with open(path.join(here, 'README.rst'), encoding='utf-8') as f: +with open(path.join(here, 'README.md'), encoding='utf-8') as f: long_description = f.read() setup(