Merge pull request #103 from ImperialCollegeLondon/docs

Add documentation on customisations

Pipfile

@@ -8,6 +8,15 @@ check-manifest = ">=0.25"
 pre-commit = "*"
 pytest-invenio = "*"
 pytest-mypy = "*"
+mkdocs = "*"
+mkdocs-material = "*"
+mkdocs-gen-files = "*"
+mkdocs-literate-nav = "*"
+mkdocs-section-index = "*"
+mkdocstrings-python = "*"
+# Avoid pytest>=8 as dependency resolution is not giving a compatible version of pluggy
+# Manifests as: https://github.com/pytest-dev/pytest/issues/12144
+pytest = "<8"
 
 [packages]
 ic-data-repo = {editable=true, path="./site"}

README.md

@@ -1,6 +1,23 @@
 # Imperial Fair Data Repository
 
-Welcome to your InvenioRDM instance.
+This repository contains the source code for the Imperial Fair Data Repository. It is an
+instance of [InvenioRDM](https://inveniordm.docs.cern.ch/) customised and configured for
+use by Imperial.
+
+See the documentation at
+<https://imperialcollegelondon.github.io/fair-data-repository/>.
+
+## Features
+
+In addition to the base InvenioRDM functionality, the following features are
+implemented:
+
+- Imperial College London branding.
+- Login with Imperial College London single sign-on.
+- Customised metadata schema supporting only datasets.
+- A centralised review and approval process for all deposits.
+
+See the [customisation documentation] for technical details
 
 ## Getting started
 
@@ -143,6 +160,7 @@ Instructions for accessing and working with realistic test data records are prov
 the [test_data directory].
 
 [configuration approach]: https://inveniordm.docs.cern.ch/install/configuration/
+[customisation documentation]: https://imperialcollegelondon.github.io/fair-data-repository/customisation/
 [getting started]: #getting-started
 [invenio-cli]: https://github.com/inveniosoftware/invenio-cli
 [pre-commit]: https://pre-commit.com/

docs/customisation.md

@@ -0,0 +1,73 @@
+We have made a variety of customisations to the base InvenioRDM app. These are potential
+pain points, particularly when upgrading to a new version of InvenioRDM. On upgrade all
+of the below should be carefully checked to ensure that they are still working as
+intended.
+
+## UI Updates
+
+### Layout and Styling
+
+Changes have been made to apply Imperial College London branding to the site. Changes
+have been made to style sheets via overrides in the `assets/less/site` directory. HTML
+templates have also been overriden in the `templates/semantic-ui` directory. The layout
+and styling customisations shoud be carefully rechecked on upgrade (particularly of
+`invenio-app-rdm`) to ensure that they are still working as intended.
+
+### Hiding Communities Feature
+
+InvenioRDM provides a feature for creating communities of deposits with an associated
+review and approval process for publication. In order to facilitate a central review
+process by the library for all deposits created a single Imperial wide community and
+have hidden references to communities in the UI. This was implemented via a style sheet
+override in [PR #97].
+
+### Deposit Form
+
+Some changes to the deposit form have made use of the support in InvenioRDM for
+overriding React components. See [InvenioRDM Docs: How to override UI React components]
+for more details. Overriden components are stored in
+`assets/js/invenio_app_rdm/overridableRegistry/mapping.js`. In summary:
+
+- The `creators` field has been customised to remove the `role` subfield as this was
+  considered confusing and to provide better alignment with the Datacite metadata
+  schema. Implemented by the custom component `OptionalRoleCreatibutorsField` that
+  allows control over whether the role subfield is displayed as well as the display of
+  clarifying help text. The implementation of `OptionalRoleCreatibutorsField`
+  unfortunately required extensive copy-pasting of the original [CreatibutorsField]
+  component so any updates to `invenio-rdm-records` should be carefully checked and any
+  changes manually ported over.
+- The `contributors` field has been customised to add additional help text. This is also
+  implemented using the custom `OptionalRoleCreatibutorsField` component.
+- The following fields have been hidden - `resource_type`, `publisher`,
+  `publication_date` and `references`. This has been implemented by overriding with the
+  custom `HiddenField` component. Some values have still had a default value set where
+  we want values to be present in the metadata but not editable by the user.
+- The `description` field has been customised to use a standard textarea rather than a
+  rich text editor as it was considered that plain text was more appropriate for this
+  field.
+- The `license` field has been customised to provide a selection of licenses from a
+  fixed list. Implemented by the custom component `LimitedLicenseField`. Similar to the
+  `OptionalRoleCreatibutorsField` this required extensive copy-pasting of the original
+  [LicensesField] component so the same checks and changes should be applied on update
+  of `invenio-rdm-records`.
+
+Other customisations have used the [APP_RDM_DEPOSIT_FORM_DEFAULTS] setting (set in
+`site/ic_data_repo/config/settings.py`). In summary:
+
+- `resource_type` has been set to "dataset".
+- `publication_data` is set to the current date.
+- `rights` is set to the CC-BY-4.0 license.
+- `publisher` is set to "Imperial College London".
+- `creators` is set to the logged in user.
+
+## Authentication
+
+Authentication via Imperial SSO is handled by the `ic_data_repo.auth.oauth` module. This
+implements an `info_handler` function that extracts user information the SSO response.
+Relevant settings for are set in `ic_data_repo.config.settings`.
+
+[app_rdm_deposit_form_defaults]: https://github.com/inveniosoftware/invenio-app-rdm/blob/af193c7a5fcb728343c7898ac4f52a5a5b44c95a/invenio_app_rdm/config.py#L917-L940
+[creatibutorsfield]: https://github.com/inveniosoftware/invenio-rdm-records/blob/v10.9.1/invenio_rdm_records/assets/semantic-ui/js/invenio_rdm_records/src/deposit/fields/CreatibutorsField/CreatibutorsField.js
+[inveniordm docs: how to override ui react components]: https://inveniordm.docs.cern.ch/develop/howtos/override_components/
+[licensesfield]: https://github.com/inveniosoftware/invenio-rdm-records/blob/v10.9.1/invenio_rdm_records/assets/semantic-ui/js/invenio_rdm_records/src/deposit/fields/License/LicenseField.js
+[pr #97]: https://github.com/ImperialCollegeLondon/fair-data-repository/pull/97/files

mkdocs.yml

@@ -0,0 +1,38 @@
+site_name: Imperial College London Fair Data Repository
+
+watch: [site/ic_data_repo]
+
+site_dir: docs_site
+
+theme:
+  name: material
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+plugins:
+  - search
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_source: true
+            show_root_heading: true
+            show_category_heading: true
+            merge_init_into_class: true
+          paths: [.]
+
+nav:
+  - Home: index.md
+  - Customisation: customisation.md