docs: update README

Author: aleks-iv

README.md

@@ -2,121 +2,182 @@
 
 # ckanext-scientometrics
 
-**TODO:** Put a description of your extension here:  What does it do? What features does it have? Consider including some screenshots or embedding a video!
+Scientometrics metrics for CKAN users. The extension lets you:
 
+- store author identifiers (per source) in user extras (`plugin_extras`)
+- fetch author-level metrics from external providers
+- persist fetched metrics in dedicated DB tables
+- display selected metrics on the user page
 
-## Requirements
+Supported sources (as implemented):
 
-**TODO:** For example, you might want to mention here which versions of CKAN this
-extension works with.
+- Google Scholar (author profile metrics)
+- Semantic Scholar (author metrics)
+- OpenAlex (author metrics)
 
-If your extension works across different versions you can add the following table:
+## How it works
 
-Compatibility with core CKAN versions:
+- User author identifiers are stored in the user `plugin_extras` under `scim`:
+  keys like `<source>_author_id` (e.g. `google_scholar_author_id`).
+- Metrics are fetched via per-source extractors and stored in:
+  - `scim_user_metric` (per user + source)
+  - `scim_dataset_metric` (reserved for dataset metrics; currently only model/migration exist)
+- The user page template can render cards for enabled sources using the stored metrics.
 
-| CKAN version    | Compatible?   |
-| --------------- | ------------- |
-| 2.6 and earlier | not tested    |
-| 2.7             | not tested    |
-| 2.8             | not tested    |
-| 2.9             | not tested    |
+## Usage
 
-Suggested values:
+### 1) Configure enabled sources
 
-* "yes"
-* "not tested" - I can't think of a reason why it wouldn't work
-* "not yet" - there is an intention to get it working
-* "no"
+Enable the plugin in CKAN config:
 
+```ini
+ckan.plugins = ... scientometrics
+```
 
-## Installation
+Configure which metric sources are enabled:
 
-**TODO:** Add any additional install steps to the list below.
-   For example installing any non-Python dependencies or adding any required
-   config settings.
+```ini
+ckanext.scientometrics.enabled_metrics = google_scholar semantic_scholar openalex
+ckanext.scientometrics.show_on_user_page = true
+```
 
-To install ckanext-scientometrics:
+### 2) Add author IDs to a user
 
-1. Activate your CKAN virtual environment, for example:
+In the user edit form, the extension adds extra fields (one per enabled source).
+The values are stored under `plugin_extras["scim"]` as:
 
-     . /usr/lib/ckan/default/bin/activate
+- `google_scholar_author_id`
+- `semantic_scholar_author_id`
+- `openalex_author_id`
 
-2. Clone the source and install it on the virtualenv
+### 3) Update metrics for a user (action)
 
-    git clone https://github.com/aleks-iv/ckanext-scientometrics.git
-    cd ckanext-scientometrics
-    pip install -e .
-	pip install -r requirements.txt
+The extension provides actions to fetch and store metrics. A typical call:
 
-3. Add `scientometrics` to the `ckan.plugins` setting in your CKAN
-   config file (by default the config file is located at
-   `/etc/ckan/default/ckan.ini`).
+- `scim_update_user_metrics` with:
+  - `user_id` (id or name)
+  - `requested_sources` (optional list of sources; defaults to enabled sources)
 
-4. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:
+Stored records are keyed by `(user_id, source)` in `scim_user_metric`.
 
-     sudo service apache2 reload
+To retrieve stored metrics:
 
+- `scim_get_user_metrics` with:
+  - `user_id`
 
-## Config settings
+Returns a dict keyed by `source`, where each value is built from the stored JSON metrics
+plus metadata like status and external references (when present).
 
-None at present
+### 4) Update metrics for all users (CLI)
 
-**TODO:** Document any optional config settings here. For example:
+The extension exposes a CLI command:
 
-	# The minimum number of hours to wait before re-checking a resource
-	# (optional, default: 24).
-	ckanext.scientometrics.some_setting = some_default_value
+```bash
+ckan scim update-user-metrics
+```
 
+Options:
 
-## Developer installation
+- `--user-ids <id>` (repeatable): update only specified user IDs
+- `--requested-sources <source>` (repeatable): update only specified sources
 
-To install ckanext-scientometrics for development, activate your CKAN virtualenv and
-do:
+If no `--user-ids` are provided, it updates all users.
 
-    git clone https://github.com/aleks-iv/ckanext-scientometrics.git
-    cd ckanext-scientometrics
-    python setup.py develop
-    pip install -r dev-requirements.txt
+## Database
 
+This extension creates two tables:
 
-## Tests
+- `scim_user_metric`
+  - unique constraint: `(user_id, source)`
+  - stores:
+    - `metrics` (JSONB)
+    - `external_id`, `external_url`
+    - `status`
+    - timestamps
+    - `extras` (JSONB for future metadata)
+
+- `scim_dataset_metric`
+  - unique constraint: `(package_id, source)`
+  - same structure as user metrics table
+
+Foreign keys are configured with `ondelete="CASCADE"`.
+
+## Requirements
+
+Compatibility with core CKAN versions:
+
+| CKAN version    | Compatible?   |
+| --------------- | ------------- |
+| 2.9 and earlier | no    |
+| 2.10+           | yes    |
 
-To run the tests, do:
+(Tests run in CI on a CKAN 2.11 container.)
 
-    pytest --ckan-ini=test.ini
+## Installation
 
+To install ckanext-scientometrics:
 
-## Releasing a new version of ckanext-scientometrics
+1. Activate your CKAN virtual environment, for example:
 
-If ckanext-scientometrics should be available on PyPI you can follow these steps to publish a new version:
+   ```bash
+   . /usr/lib/ckan/default/bin/activate
+   ```
 
-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. Clone the source and install it on the virtualenv:
 
-2. Make sure you have the latest version of necessary packages:
+   ```bash
+   git clone https://github.com/aleks-iv/ckanext-scientometrics.git
+   cd ckanext-scientometrics
+   pip install -e .
+   pip install -r requirements.txt
+   ```
 
-    pip install --upgrade setuptools wheel twine
+3. Add `scientometrics` to the `ckan.plugins` setting in your CKAN config file
+   (by default `/etc/ckan/default/ckan.ini`).
 
-3. Create a source and binary distributions of the new version:
+4. Restart CKAN (eg on Ubuntu + Apache):
 
-       python setup.py sdist bdist_wheel && twine check dist/*
+   ```bash
+   sudo service apache2 reload
+   ```
 
-   Fix any errors you get.
+## Config settings
 
-4. Upload the source distribution to PyPI:
+- `ckanext.scientometrics.enabled_metrics` (type: list)
+  - default: `google_scholar semantic_scholar openalex`
+  - enabled sources; controls which user fields are shown and which sources can be updated
 
-       twine upload dist/*
+- `ckanext.scientometrics.show_on_user_page` (type: bool)
+  - default: `true`
+  - show metrics cards on the user page
 
-5. Commit any outstanding changes:
+Example:
 
-       git commit -a
-       git push
+```ini
+ckan.plugins = ... scientometrics
+
+ckanext.scientometrics.enabled_metrics = openalex semantic_scholar
+ckanext.scientometrics.show_on_user_page = true
+```
+
+## Developer installation
+
+To install for development:
+
+```bash
+git clone https://github.com/aleks-iv/ckanext-scientometrics.git
+cd ckanext-scientometrics
+pip install -e .
+pip install -r dev-requirements.txt
+```
+
+## Tests
 
-6. 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.1 then do:
+To run tests:
 
-       git tag 0.0.1
-       git push --tags
+```bash
+pytest --ckan-ini=test.ini
+```
 
 ## License