Skip to content
Snippets Groups Projects
README.md 6.93 KiB
Newer Older
  • Learn to ignore specific revisions
  • root's avatar
    root committed
    # ckanext-odsh
    
    
    This CKAN extension provides custom features and the layout of the Open Data Portal
    Schleswig-Holstein.
    
    root's avatar
    root committed
    
    
    ## Table of Contents
    
    root's avatar
    root committed
    
    
    - [Getting Started](#getting-started)
    - [Contributing](#contributing)
    - [Versioning](#versioning)
    - [Acknowledgement](#acknowledgement)
    - [Authors](#authors)
    - [License](#license)
    
    root's avatar
    root committed
    
    
    ## Getting Started
    
    root's avatar
    root committed
    
    
    These instructions will get you a copy of the project up and running on your local
    machine for development and testing purposes.
    
    root's avatar
    root committed
    
    
    ### Prerequisites
    
    root's avatar
    root committed
    
    
    This project requires the following CKAN extensions to work properly:
    
    root's avatar
    root committed
    
    
    - [ckanext-archiver](https://github.com/ckan/ckanext-archiver)
    
    - [ckanext-dcat](https://github.com/ckan/ckanext-dcat)
    - [ckanext-dcatde](https://github.com/GovDataOfficial/ckanext-dcatde)
    
    - [ckanext-harvest](https://github.com/ckan/ckanext-harvest)
    
    - [ckanext-qa](https://github.com/ckan/ckanext-qa)
    
    - [ckanext-spatial](https://github.com/ckan/ckanext-spatial)
    
    - [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_collections`, `odsh_dcat_harvest`,
       `kiel_harvester` and `statistikamtnord_harvester` to the plugin list, to enable
       custom functionality, e.g.:
    
          ckan_harvester
          dcat
          dcatde
          dcatde_rdf_harvester
          harvest
          image_view
          kiel_harvester
          odsh
          odsh_autocomplete
          odsh_dcat_harvest
    
          qa
          archiver
          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 | Default | Description
    --------- | ---- | ------- | -----------
    `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` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/language_mapping.json` | Absolute path to language mapping file.
    `ckanext.odsh.spatial.mapping` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/schleswig-holstein_geojson.csv` | Absolute path to spatial mapping file. The mapping file is expected to be a tab-separated file with three columns: URI, spatial text, and JSON geometry.
    
    `ckanext.odsh.applicable_legislation` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/applicable_legislation.json` | Absolute path to applicable legislation mapping file.
    `ckanext.odsh.hvd_categories` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/hvd_categories.json` | Absolute path to HVD category mapping file.
    
    `ckanext.odsh.resource_formats_fallback_filepath` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/fileformats.rdf` | Absolute path to resource formats fallback file.
    
    `ckanext.odsh.require_at_least_one_category` | `boolean` | `False` |  Indicates whether the presence of at least one category is required during validation.
    
    `ckanext.odsh.require_spatial_uri` | `boolean` | `False` | Indicates whether a spatial URI is required for the dataset.
    
    `ckanext.odsh.is_optional_temporal_start` | `boolean` | `False` | Indicate whether the `temporal_start` property is considered optional or not during validation.
    `ckanext.odsh.download_proxy` | `string` | `None` | Use proxy server to access the web, e.g., `http://1.2.3.4:4123`.
    
    `ckanext.odsh.copy_remote_resources` | `boolean` | `False` | Indicates whether remote resources should be copied when creating a resource.
    
    `ckanext.odsh.lenient_with` | `string` | Empty string | Comma seperated list of organization IDs for which certain validations should be more lenient, e.g., `09871195-cd0a-4767-9396-276404c940d9,6389d8d9-4eed-472f-9220-4cc2dd82fb90`.
    
    `ckanext.odsh.testuser` | `string` | `None` | Name of user for testing.
    `ckanext.odsh.testuserpass` | `string` | `None` | Password of user for testing.
    
    `ckanext.odsh.matomo_enabled` | `boolean` | `False` | Enable Matomo tracking.
    `ckanext.odsh.matomo_base_uri` | `string` | `None` | Matomo tracker base URI.
    `ckanext.odsh.matomo_site_id` | `string` | `None` | Matomo site id.
    
    Additionaly you might want to set the following configuration parameters:
    
    ```ini
    licenses_group_url = file://<path_to_ckan>/default/src/ckanext-odsh/ckanext/odsh/resources/licenses.json
    ```
    
    
    To ensure the quality and functionality of the `ckanext-odsh` extension, a comprehensive
    test suite is provided. You can follow the instructions below to run the tests:
    
    1. Activate the virtual environment associated with your project, for example:
    
        ```sh
        . /usr/lib/ckan/default/bin/activate
        ```
    
    2. From the `ckanext-odsh` base directory, execute the following commands:
    
        ```sh
        pytest ckanext/odsh/tests/
        ```
    
    Running these commands will initiate the test suite, which will automatically execute
    
    various test cases and verify the expected behavior of the extension.
    
    ### Internationalization
    
    To enable internationalization of strings, follow these steps:
    
    1. Ensure that you are in the appropriate environment and located within the extensions directory.
    
    2. Run the following command:
    
        ```sh
        python setup.py extract_messages
        ```
    
    
    Thorge Petersen's avatar
    Thorge Petersen committed
    This command will generate a template PO file named `ckanext/odsh/i18n/ckanext-odsh.pot`. You can utilize tools like [POEdit](https://poedit.net/) to work with this file.
    
    
    For detailed instructions on internationalizing strings in extensions, refer to CKAN's official guide on [translating extensions](https://docs.ckan.org/en/latest/extensions/translating-extensions.html).
    
    
    ## 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/master)
    
    who participated in this project.
    
    ## License
    
    
    This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE - see the
    [LICENSE](./LICENSE) file for details.