From f0eb3b03c5459a03f9a89e8c2a25b45d438ebf92 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Thu, 20 Jun 2024 16:00:36 +0200 Subject: [PATCH] [DOC] render library listing in doc (#505) * [DATALAD] Added subdataset * lib in doc --- .gitignore | 2 + .gitmodules | 4 + docs/FAQ.md | 11 -- docs/library.md | 14 ++ docs/project-structure.md | 3 +- .../collecting-demographics-information.md | 148 ------------------ library | 1 + macros/__init__.py | 9 ++ macros/macros.py | 68 ++++++++ macros/main.py | 32 ++++ mkdocs.yml | 8 +- requirements.txt | 4 +- templates/library_table.jinja | 5 + 13 files changed, 145 insertions(+), 164 deletions(-) create mode 100644 .gitmodules create mode 100644 docs/library.md delete mode 100644 docs/tutorials/collecting-demographics-information.md create mode 160000 library create mode 100644 macros/__init__.py create mode 100644 macros/macros.py create mode 100644 macros/main.py create mode 100644 templates/library_table.jinja diff --git a/.gitignore b/.gitignore index 3046e3a30..d4c3c92cf 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,8 @@ activities/.DS_Store protocols/.DS_Store +__pycache__ + .idea/ node_modules diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..f2af08f53 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "library"] + path = library + url = https://github.com/ReproNim/reproschema-library.git + datalad-url = https://github.com/ReproNim/reproschema-library.git diff --git a/docs/FAQ.md b/docs/FAQ.md index 52398cfb8..18679c78f 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -53,17 +53,6 @@ once you have opened that page on github that will open this URL: If you want to visualize the graph represented by the JSON-LD file, we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld). - -### Which assessments tools will/are supporting this standard? - -At the moment, all the assessments that support this standard are listed in [this folder](https://github.com/ReproNim/reproschema-library/tree/master/activities) or the [reproschema-library repository](https://github.com/ReproNim/reproschema-library). - -If you want to see those different tools in action using our user interface, -you can explore them on [schema.repronim.org/](https://schema.repronim.org/rl/). - -The ReproSchema is also used to develop a checklist to [improve methods and results reporting in neuroimaging](https://github.com/ohbm/cobidas). - - ## Linked data and semantic web ## What is the semantic web? diff --git a/docs/library.md b/docs/library.md new file mode 100644 index 000000000..8c318a7e0 --- /dev/null +++ b/docs/library.md @@ -0,0 +1,14 @@ +--- +hide: + - toc +--- +# Reproschema library + +At the moment, all the assessments that support this standard are listed in [this folder](https://github.com/ReproNim/reproschema-library/tree/master/activities) of the [reproschema-library repository](https://github.com/ReproNim/reproschema-library). + +For convenience we are listing them in the table below. + +If you want to see those different tools in action using our user interface, +you can explore them on [schema.repronim.org/](https://schema.repronim.org/rl/). + +{{ MACROS___library_table() }} diff --git a/docs/project-structure.md b/docs/project-structure.md index 8de0367ac..98b197ef1 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -51,8 +51,7 @@ questionnaire for your next participant or patient. Also you can mix and match items from this library, knowing that the information is tracked in your protocol. All assessments are listed in [the `activity` folder](https://github.com/ReproNim/reproschema-library/tree/master/activities) -and are served [here](https://schema.repronim.org/rl/) if you want to visualize -them. +and are served [here](https://schema.repronim.org/rl/) if you want to visualize them. - **Standard Alignment:** Each element in the library aligns with the ReproSchema framework, ensuring uniformity in terms and structure and upholding validation protocols for consistency across the ecosystem. - **Research Protocol Integration:** Researchers can utilize these assessments in various combinations to align with specific protocol needs, customizing their application per study objectives. This process can be integrated using the reproschema-protocol-cookiecutter for constructing user interfaces. diff --git a/docs/tutorials/collecting-demographics-information.md b/docs/tutorials/collecting-demographics-information.md deleted file mode 100644 index 003d85715..000000000 --- a/docs/tutorials/collecting-demographics-information.md +++ /dev/null @@ -1,148 +0,0 @@ -# Collecting information about your participant - -Before you go and start creating new activities and items to collect the names, surnames and other demographics of your participants make sure you have had a look at these items on the reproschema library: - -See the [demographics_and_background_information_v1](https://github.com/ReproNim/reproschema-library/tree/master/activities/demographics_and_background_information_v1/items) folder: - -```text -demographics_and_background_information_v1/ -└── items - ├── age_months - ├── age_years - ├── ann_fam_income - ├── child_out_psych_cur - ├── child_out_psych_ever - ├── countryOfBirth - ├── demo_init - ├── demo_rpt_date - ├── document - ├── doe - ├── education_level - ├── email - ├── ethnic_category - ├── ethnic_category_informant - ├── fluentLanguages - ├── fullName - ├── handedness - ├── healthCondition - ├── inpatient_psych - ├── inpatient_treat_age - ├── inpatient_treat_dur - ├── inpatient_treatments - ├── interviewed_who - ├── interview_type - ├── knownLanguages - ├── last_period - ├── medication - ├── menarche_start - ├── meneses - ├── mentalHealth - ├── nativeLanguage - ├── other_persons_instructions - ├── outpatient_treat_age - ├── outpatient_treatments - ├── outpatient_treat_weeks - ├── parent_relationship - ├── parent_relationship_1 - ├── parent_relationship_2 - ├── participant_education - ├── participant_id - ├── particpant_grade_level - ├── person1_education - ├── person1_id - ├── person1_occ_lvl - ├── person1_other_id - ├── person2_education - ├── person2_exist - ├── person2_id - ├── person2_occ_lvl - ├── person2_other_id - ├── race_category - ├── race_category_informant - ├── raceEthnicity - ├── record_id - ├── religious_category - ├── sex - ├── share_data - ├── stateOfBirth - ├── stateOfResidence - └── verification_id -``` - -```json -{ - "@context": [ "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - { - "demo": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/demographics_and_background_information_v1/items" - } - ], - "@type": "reproschema:Activity", - "@id": "demographics.jsonld", - "prefLabel": "demographics", - "description": "information about the participant", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "ui": { - "order": [ - "demo:participant_id", - "demo:fullName", - "demo:sex", - "demo:age_years", - "demo:email", - "demo:participant_education", - "demo:nativeLanguage", - "demo:healthCondition", - "demo:mentalHealth", - "demo:share_data", - "demo:medication" - ], - "shuffle": false, - "addProperties": [ - { - "variableName": "participant_id", - "isAbout": "demo:participant_id" - }, - { - "variableName": "fullName", - "isAbout": "demo:fullName" - }, - { - "variableName": "sex", - "isAbout": "demo:sex" - }, - { - "variableName": "age_years", - "isAbout": "demo:age_years" - }, - { - "isAbout": "demo:email", - "variableName": "email" - }, - { - "isAbout": "demo:participant_education", - "variableName": "participant_education" - }, - { - "isAbout": "demo:nativeLanguage", - "variableName": "nativeLanguage" - }, - { - "isAbout": "demo:healthCondition", - "variableName": "healthCondition" - }, - { - "isAbout": "demo:mentalHealth", - "variableName": "mentalHealth" - }, - { - "isAbout": "demo:share_data", - "variableName": "share_data" - }, - { - "isAbout": "demo:medication", - "variableName": "medication" - } - ] - } -} -``` diff --git a/library b/library new file mode 160000 index 000000000..9be140d02 --- /dev/null +++ b/library @@ -0,0 +1 @@ +Subproject commit 9be140d0297ae0671d50466448ae67dea86d3bfd diff --git a/macros/__init__.py b/macros/__init__.py new file mode 100644 index 000000000..286bef408 --- /dev/null +++ b/macros/__init__.py @@ -0,0 +1,9 @@ +from .macros import ( + library_table, +) +from .main import define_env + +__all__ = [ + "define_env", + "library_table", +] diff --git a/macros/macros.py b/macros/macros.py new file mode 100644 index 000000000..58df9c64c --- /dev/null +++ b/macros/macros.py @@ -0,0 +1,68 @@ +from pathlib import Path +import json + +import ruamel.yaml +from jinja2 import Environment, FileSystemLoader, select_autoescape + +yaml = ruamel.yaml.YAML() +yaml.indent(mapping=2, sequence=4, offset=2) + +ROOT = Path(__file__).parents[1] + +TEMPLATES_DIR = ROOT / "templates" + +LIBRARY_DIR = ROOT / "library" + +SCHEMA_DIR = ROOT / "linkml-schema" + + +def return_jinja_env() -> Environment: + return Environment( + loader=FileSystemLoader(TEMPLATES_DIR), + autoescape=select_autoescape(), + lstrip_blocks=True, + trim_blocks=True, + ) + + +def library_table() -> str: + + LIBRARY_URL = "https://github.com/ReproNim/reproschema-library" + + activities = [] + + for activity_path in (LIBRARY_DIR / "activities").iterdir(): + + if not activity_path: + continue + + for file in activity_path.glob("*"): + + if file.is_dir() or file is None or "valueConstraints" in file.stem: + continue + + with open(file) as f: + content = json.load(f) + + activities.append( + { + "name": content["@id"], + "description": ( + content["description"] if "description" in content else "" + ), + "uri": f"{LIBRARY_URL}/tree/master/activities/{activity_path.stem}/{file.stem}{file.suffix}", + } + ) + + env = return_jinja_env() + template = env.get_template("library_table.jinja") + + return template.render(activities=activities) + + +def main(): + print(library_table()) + + +if __name__ == "__main__": + main() diff --git a/macros/main.py b/macros/main.py new file mode 100644 index 000000000..c87b006d1 --- /dev/null +++ b/macros/main.py @@ -0,0 +1,32 @@ +"""This package is used to build elements from data into +MarkDown format for the specification text. + +Functions decorated in "define_env()" are callable throughout the +specification and are run/rendered with the mkdocs plugin "macros". +""" + +import os +import sys + +code_path = os.path.abspath(os.path.join(os.path.dirname(__file__))) +sys.path.append(code_path) + +import macros # noqa E402 + + +def define_env(env): + """Define variables, macros and filters for the mkdocs-macros plugin. + + Parameters + ---------- + env : :obj:`macros.plugin.MacrosPlugin` + An object in which to inject macros, variables, and filters. + + Notes + ----- + "variables" are the dictionary that contains the environment variables + "macro" is a decorator function, to declare a macro. + + Macro aliases must start with "MACROS___" + """ + env.macro(macros.library_table, "MACROS___library_table") diff --git a/mkdocs.yml b/mkdocs.yml index 5721e4d33..e7ad7b162 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,8 +54,8 @@ nav: - Create new items: "tutorials/create-new-items.md" - Finalize the protocol: "tutorials/finalizing-the-protocol.md" - Translate a questionnaire: "tutorials/translating-an-activity.md" - - Demographic information : "tutorials/collecting-demographics-information.md" - - Tips to make your life easier: "tutorials/tips-to-make-your-life-easier.md" + - Tips: tutorials/tips-to-make-your-life-easier.md + - Library: library.md - FAQ: "FAQ.md" - Contributing: "CONTRIBUTING.md" @@ -75,12 +75,16 @@ markdown_extensions: - pymdownx.snippets: auto_append: - includes/abbreviations.md + - tables - toc: anchorlink: true watch: - includes + - linkml-schema plugins: - search - tags + - macros: + module_name: macros/main diff --git a/requirements.txt b/requirements.txt index a9afbecb6..044ec90ae 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,5 @@ -rdflib==5.0.0 +mkdocs-macros-plugin mkdocs-material pymdown-extensions +rdflib==5.0.0 +ruamel.yaml diff --git a/templates/library_table.jinja b/templates/library_table.jinja new file mode 100644 index 000000000..02cfd1a56 --- /dev/null +++ b/templates/library_table.jinja @@ -0,0 +1,5 @@ +| Activity | Description | URI | +| :------ | :---------- | :-- | +{% for activity in activities %} +| {{ activity.name }} | {{ activity.description }} | [link]({{ activity.uri }}) | +{% endfor %}