[DOC] extract some sections from tutorial into "how to guide" (#506)

* refactor * tmp * update visualize section --------- Co-authored-by: Yibei Chen <[email protected]>
ReproNim · Jun 20, 2024 · a893416 · a893416
1 parent f0eb3b0
commit a893416
Show file tree

Hide file tree

Showing 5 changed files with 125 additions and 80 deletions.
diff --git 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
@@ -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
@@ -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
diff --git 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"