From a8934162a1636a802e49c88dedf185c90292b9a2 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Thu, 20 Jun 2024 16:23:34 +0200 Subject: [PATCH] [DOC] extract some sections from tutorial into "how to guide" (#506) * refactor * tmp * update visualize section --------- Co-authored-by: Yibei Chen --- docs/FAQ.md | 23 ++--- docs/how-to/validation.md | 89 +++++++++++++++++++ docs/how-to/visualize.md | 26 ++++++ .../tips-to-make-your-life-easier.md | 60 ------------- mkdocs.yml | 7 +- 5 files changed, 125 insertions(+), 80 deletions(-) create mode 100644 docs/how-to/validation.md create mode 100644 docs/how-to/visualize.md delete mode 100644 docs/tutorials/tips-to-make-your-life-easier.md diff --git a/docs/FAQ.md b/docs/FAQ.md index 18679c78f..56eb97ace 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -31,27 +31,14 @@ **🛠 Work in progress 🛠** --> -### How can I visualize the schema for a `protocol` or an `activity`? +### Which assessments tools will/are supporting this standard? -If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on [schema.repronim.org](https://schema.repronim.org/rl). +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 just want to view a protocol or activity you are developing using the `reproschema-ui`, -you can pass the URL of the schema to the `url` query parameter like this: +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/). -```https://schema.repronim.org/ui/#/?url=url-to-your-schema``` - -If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. -For example, our demo protocol can be accessed at this URL: - -[https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) - -But to get access to the raw content of that file you must click on the `Raw` button -once you have opened that page on github that will open this URL: - -[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema). - -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). +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 diff --git a/docs/how-to/validation.md b/docs/how-to/validation.md new file mode 100644 index 000000000..4c1a49d2e --- /dev/null +++ b/docs/how-to/validation.md @@ -0,0 +1,89 @@ +# Validation + +### Validating your schema + +If you want to validate a schema you have created: + +- install the reproschema python tools + +```bash +pip install reproschema +``` + +- run its `validate` command + +```bash +reproschema --log-level DEBUG validate PATH_TO_VALIDATE +``` + +!!! note + + You can validate a single file or all the files in a folder and its subfolder. + +### Automating validation + +If you are hosting your schema on a github repository, +you can automate its validation with a with GitHub CI workflow. + +For example if your repository is structured like this: + +```text +├── protocols +│ └── protocol-1.jsonld +├── activities +│ ├── items +│ │ └── item-1.jsonld +│ └── activity-1.jsonld +└── README.md +``` + +create a `.github/workflows/validate.yml` file in this repository. + +```text hl_lines="1-3" +├── .github # hidden github folder +│ └── workflows +│ └── validate.yml # file the actions used to validate your schema +├── protocols +│ └── protocol-1.jsonld +├── activities +│ ├── items +│ │ └── item-1.jsonld +│ └── activity-1.jsonld +└── README.md +``` + +Content of `validate.yml`: + +```yaml +name: validation + +on: + push: + branches: [ main ] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.12 + - name: Install dependencies + run: | + python -m pip install --upgrade pip setuptools + pip install reproschema-py + - name: validate + run: | + reproschema validate protocols + reproschema validate activities +``` + +!!! note + + Note that if you have created your schema + using the [reproschema cookie cutter](../user-guide/create-new-protocol.md) + then a validation workflow should already be included in your repository. diff --git a/docs/how-to/visualize.md b/docs/how-to/visualize.md new file mode 100644 index 000000000..71a804e58 --- /dev/null +++ b/docs/how-to/visualize.md @@ -0,0 +1,26 @@ +# Visualize + +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](../FAQ.md#from-json-to-json-ld). + +If you want to visualize the protocol or the activity you have created as a web form, +you can use the [reproschema-ui](https://github.com/ReproNim/reproschema-ui) to preview it. +To do so you can pass the URL to your protocol or activity as a query +to the [reproschema-ui app](https://www.repronim.org/reproschema-ui/) + +```https://www.repronim.org/reproschema-ui/#/?url=url-to-your-schema``` + +If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. +For example, our demo protocol can be accessed at this URL: + +[https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) + +But to get access to the raw content of that file you must click on the `Raw` button +once you have opened that page on github that will open this URL: + +[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema). + +So in the end the URL to preview this protocol as a web form would be: + +[https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema]( +https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) diff --git a/docs/tutorials/tips-to-make-your-life-easier.md b/docs/tutorials/tips-to-make-your-life-easier.md deleted file mode 100644 index e5a668421..000000000 --- a/docs/tutorials/tips-to-make-your-life-easier.md +++ /dev/null @@ -1,60 +0,0 @@ -# Tips to make your life easier - -## Validating your JSON files - -First, make sure your syntax is in correct JSON-LD format. -Test all files with `@context` from command line: - -```bash -npm install -g jsonlint -grep -r "@context" . | cut -d: -f1 | xargs -I fname jsonlint -q fname -``` - -Or test individual files on the [json linter website](https://jsonlint.com/). - -## Validating your schema - -```bash -pip install reproschema requests_cache -reproschema -l DEBUG validate activities -``` - -## Automating those checks - -It can be quickly become cumbersome to type some of the commands described above -to always make sure the files you have created are valid. - -Thankfully though there are ways to automate those checks and integrate them -into your workflow. They rely on using some of the features of Github or Git. - -### Github actions - -The first one is using Github actions to let Github perform those checks for you -every time there some new content is added on a repository. - -To set those up you simply need to create a `.github/workflows` folder inside the repository where you are working. -This will contain all the workflows (a set of "actions") that Github has to run on this repository. -Each workflow is described by a `yml` file. - -For example you could create a `validate.yml` file in this repository. - -```text -├── .git # hidden git folder -├── .github # hidden github folder -│ └── workflows -│ └── validate.yml # file the actions used to validate your schema -├── protocols -│ ├── README-en.md -│ └── protocol-1.jsonld -├── activities -│ ├── items -│ │ └── item-1.jsonld -│ └── activity-1.jsonld -└── README.md -``` - -The content of `validate.yml` file would look like this. - -```yaml ---8<-- ".github/workflows/validate.yml" -``` diff --git a/mkdocs.yml b/mkdocs.yml index e7ad7b162..ddbfeb653 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,8 +54,11 @@ 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" - - Tips: tutorials/tips-to-make-your-life-easier.md - - Library: library.md + - Demographic information : "tutorials/collecting-demographics-information.md" + - How to guides: + - Validation: "how-to/validation.md" + - Visualize: "how-to/visualize.md" + - FAQ: "FAQ.md" - Contributing: "CONTRIBUTING.md"