From fe6d18c05ab8103b33062e6cd148e1e441a71947 Mon Sep 17 00:00:00 2001 From: Thorge Petersen <petersen@rz.uni-kiel.de> Date: Fri, 24 Mar 2023 10:29:27 +0100 Subject: [PATCH] Started with updating readme --- README.md | 144 ++++++++++++++++++++++++++++++++++++++++------ README.rst | 166 ----------------------------------------------------- 2 files changed, 126 insertions(+), 184 deletions(-) delete mode 100644 README.rst diff --git a/README.md b/README.md index 39eb07c8..158c5b6c 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,135 @@ # ckanext-odsh -Diese CKAN-Extension enthält die wichtigsten Features und das Layout für das Tranzparenzportal Schleswig-Holstein. -Sie ist eine Weiterentwicklung der gleichnamigen Extension, die im Zuge der Entwicklung des Open Data Portals Schleswig-Holstein entwickelt wurde. -## Branches -### master -Dieser Branch enthält den aktuell auf den Stage- bzw. Prod-Servern laufenden Code. +This CKAN extension provides custom features and the layout of the Open Data Portal Schleswig-Holstein. -### dev -Dieser Branch enthält den aktuellsten Stand mit allen fertig entwickelten Features. +## Table of Contents -### andere Branches -Für die Entwicklung neuer Features soll jeweils ein eigener Branch vom dev-Branch abgezweigt werden. Für den Branch soll ein sprechender Name gewählt werden. +- [Getting Started](#getting-started) +- [Contributing](#contributing) +- [Versioning](#versioning) +- [Acknowledgement](#acknowledgement) +- [Authors](#authors) +- [License](#license) -## Deployment auf Produktivsystem -Das Deployment auf das Produktivsystem geschieht über Ansible. Die dafür benötigten Skripte befinden sich im Repository `tpsh_deploy`. +## Getting Started -## Manuelle Installation +These instructions will get you a copy of the project up and running on your local +machine for development and testing purposes. +### Prerequisites -## Konfiguration -Die Extension benötigt Konfigurationsparameter in der CKAN-Konfigurationsdatei (z.B. `production.ini`). Die korrekten Parameter für das Produktivsystem befinden sich im Repository `tpsh_deploy` unter `resources/production.ini`. Folgende Parameter sollten für Enwicklungssysteme geändert werden: +This project requires the following CKAN extensions to work properly: -| Parameter | Erläuterung | Wert für Entwicklungssysteme | -|---------------------------------------|---------------------------------------------------------------|-------------------------------------------| -| ckanext.odsh.skip_icap_virus_check | `false` schaltet den Virus-Check ein. | `true` | -| ckanext.odsh.showtestbanner | `true` schaltet das Banner "Testsystem" ein, Muss `false` für Production-Server sein. | - | \ No newline at end of file +- [ckanext-dcat](https://github.com/ckan/ckanext-dcat) +- [ckanext-dcatde](https://github.com/GovDataOfficial/ckanext-dcatde) +- [ckanext-qa](https://github.com/ckan/ckanext-qa) +- [ckanext-archiver](https://github.com/ckan/ckanext-archiver) +- [ckanext-report](https://github.com/ckan/ckanext-report) + +### Installing + +To install ckanext-odsh: + +1. Activate your CKAN virtual environment, for example:: + + ```sh + . /usr/lib/ckan/default/bin/activate + ``` + +2. Install the ckanext-odsh Python package into your virtual environment:: + + ```sh + pip install https://code.schleswig-holstein.de/opendata/ckanext-odsh.git + ``` + +3. Add `odsh` to the `ckan.plugins` setting in your CKAN config file (by default the config file is located at `/etc/ckan/default/production.ini`). + + You may also add `odsh_autocomplete`, `odsh_dcat_harvest`, `kiel_harvester` and `statistikamtnord_harvester` to the plugin list, to enable custom functionality, e.g.: + + ```ini + ckan.plugins = + ckan_harvester + dcat + dcatde + dcat_json_harvester + dcat_json_interface + dcat_rdf_harvester + dcatde_rdf_harvester + harvest + image_view + kiel_harvester + odsh + odsh_autocomplete + odsh_dcat_harvest + qa + archiver + recline_view + report + spatial_metadata + spatial_query + statistikamtnord_harvester + stats + structured_data + text_view + ``` + +4. Restart CKAN. + +### Configuration + +The extension requires configuration parameters in the CKAN configuration file (e.g., `production.ini`). The following parameters should be set: + +Parameter | Type | Description +--------- | ----- | ----------- +ckanext.odsh.home | `string` | Absolute path to base directory, e.g., `/usr/lib/ckan/default/src/ckanext-odsh`. +ckanext.odsh.public_url | `string` | The public URL, e.g., `https://opendata.schleswig-holstein.de`. +ckanext.odsh.showtestbanner | `boolean` | `true` switches on the banner "test system". Must be `false` for production server. +ckanext.odsh.language_mapping | `string` | Absolute path to language mapping file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/language_mapping.json`. +ckanext.odsh.subject_mapping | `string` | Absolute path to subject mapping file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/subject_mapping.json`. +ckanext.odsh.spatial.mapping | `string` | Absolute path to spatial mapping file, e.g., `/usr/lib/ckan/default/src/odsh-odsh/schleswig-holstein_geojson.csv`. +ckanext.odsh.resource_formats_fallback_filepath | `string` | Absolute path to resource formats fallback file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/fileformats.rdf` +ckanext.odsh.upload_formats | `string` | E.g., `pdf`. +ckanext.odsh.require_at_least_one_category | `boolean` | E.g., `True`. +ckanext.odsh.require_spatial_uri | `boolean` | E.g., `True`. +ckanext.odsh.require_subject | `boolean` | E.g., `False`. +ckanext.odsh.is_optional_temporal_start | `boolean` | E.g., `False`. + +### Testing + +*Deprecated – will be updated soon.* + +To run the tests, do: + +```sh +nosetests --nologcapture --with-pylons=test.ini +``` + +To run the tests and produce a coverage report, first make sure you have +coverage installed in your virtualenv (`pip install coverage`) then run:: + +```sh +nosetests --nologcapture --with-pylons=test.ini --with-coverage --cover-package=ckanext.odsh --cover-inclusive --cover-erase --cover-tests +``` + +## Contributing + +To contribute to this documentation, create a branch or fork this repository, make +your changes and create a merge request. + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see +the [tags on this repository](https://code.schleswig-holstein.de/opendata/ckanext-odsh/-/tags). + +## Acknowledgement + +This extension was originally developed by [HITeC e.V](https://www.hitec-hamburg.de/). + +## Authors + +See also the list of [contributors](https://code.schleswig-holstein.de/opendata/ckanext-odsh/-/graphs/main) +who participated in this project. + +## License + +This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE - see the [LICENSE](./LICENSE) file for details. diff --git a/README.rst b/README.rst deleted file mode 100644 index 06008804..00000000 --- a/README.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. You should enable this project on travis-ci.org and coveralls.io to make - these badges work. The necessary Travis and Coverage config files have been - generated for you. - -.. image:: https://travis-ci.org//ckanext-odsh.svg?branch=master - :target: https://travis-ci.org//ckanext-odsh - -.. image:: https://coveralls.io/repos//ckanext-odsh/badge.svg - :target: https://coveralls.io/r//ckanext-odsh - -.. image:: https://pypip.in/download/ckanext-odsh/badge.svg - :target: https://pypi.python.org/pypi//ckanext-odsh/ - :alt: Downloads - -.. image:: https://pypip.in/version/ckanext-odsh/badge.svg - :target: https://pypi.python.org/pypi/ckanext-odsh/ - :alt: Latest Version - -.. image:: https://pypip.in/py_versions/ckanext-odsh/badge.svg - :target: https://pypi.python.org/pypi/ckanext-odsh/ - :alt: Supported Python versions - -.. image:: https://pypip.in/status/ckanext-odsh/badge.svg - :target: https://pypi.python.org/pypi/ckanext-odsh/ - :alt: Development Status - -.. image:: https://pypip.in/license/ckanext-odsh/badge.svg - :target: https://pypi.python.org/pypi/ckanext-odsh/ - :alt: License - -============= -ckanext-odsh -============= - -.. Put a description of your extension here: - What does it do? What features does it have? - Consider including some screenshots or embedding a video! - - ------------- -Requirements ------------- - -For example, you might want to mention here which versions of CKAN this -extension works with. - - ------------- -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-odsh: - -1. Activate your CKAN virtual environment, for example:: - - . /usr/lib/ckan/default/bin/activate - -2. Install the ckanext-odsh Python package into your virtual environment:: - - pip install ckanext-odsh - -3. Add ``odsh`` 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. For example:: - - # The minimum number of hours to wait before re-checking a resource - # (optional, default: 24). - ckanext.odsh.some_setting = some_default_value - - ------------------------- -Development Installation ------------------------- - -To install ckanext-odsh for development, activate your CKAN virtualenv and -do:: - - git clone https://github.com//ckanext-odsh.git - cd ckanext-odsh - python setup.py develop - pip install -r dev-requirements.txt - - ------------------ -Running the Tests ------------------ - -To run the tests, do:: - - nosetests --nologcapture --with-pylons=test.ini - -To run the tests and produce a coverage report, first make sure you have -coverage installed in your virtualenv (``pip install coverage``) then run:: - - nosetests --nologcapture --with-pylons=test.ini --with-coverage --cover-package=ckanext.odsh --cover-inclusive --cover-erase --cover-tests - - ---------------------------------- -Registering ckanext-odsh on PyPI ---------------------------------- - -ckanext-odsh should be availabe on PyPI as -https://pypi.python.org/pypi/ckanext-odsh. If that link doesn't work, then -you can register the project on PyPI for the first time by following these -steps: - -1. Create a source distribution of the project:: - - python setup.py sdist - -2. Register the project:: - - python setup.py register - -3. Upload the source distribution to PyPI:: - - python setup.py sdist upload - -4. Tag the first release of the project on GitHub with the version number from - the ``setup.py`` file. For example if the version number in ``setup.py`` is - 0.0.1 then do:: - - git tag 0.0.1 - git push --tags - - ----------------------------------------- -Releasing a New Version of ckanext-odsh ----------------------------------------- - -ckanext-odsh is availabe on PyPI as https://pypi.python.org/pypi/ckanext-odsh. -To publish a new version to PyPI follow these steps: - -1. Update the version number in the ``setup.py`` file. - See `PEP 440 <http://legacy.python.org/dev/peps/pep-0440/#public-version-identifiers>`_ - for how to choose version numbers. - -2. Create a source distribution of the new version:: - - python setup.py sdist - -3. Upload the source distribution to PyPI:: - - python setup.py sdist upload - -4. Tag the new release of the project on GitHub with the version number from - the ``setup.py`` file. For example if the version number in ``setup.py`` is - 0.0.2 then do:: - - git tag 0.0.2 - git push --tags -- GitLab