Skip to content

Commit 99c321c

Browse files
Remi-GauRemi-Gau
authored
[REF] refactor documentation (#487)
* add syntax highlighting where missing * move files in subfolders * rename files * update contributing info * format markdown * apply remark * fix links * fix file name * refactor jsonld snippets out of doc * more extracting of snippets * rm prettier hook * fix validation * misc * apply review suggestions * Update .github/workflows/pythonpackage.yml * fix validation * fix and refactor * fix * move FAQ * refactor * mv question * fix indents
1 parent 0c23758 commit 99c321c

36 files changed

+952
-1026
lines changed

‎.github/workflows/pythonpackage.yml

+5-3
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,16 @@ jobs:
1616

1717
steps:
1818
- uses: actions/checkout@v4
19-
- name: Set up Python 3.10
19+
- name: Set up Python
2020
uses: actions/setup-python@v5
2121
with:
22-
python-version: "3.10"
22+
python-version: 3.12
2323
- name: Install dependencies
24+
# TODO update to install from the latest version on reproschema
25+
# once https://github.com/ReproNim/reproschema-py/pull/40 has been merged and a new release has been made.
2426
run: |
2527
python -m pip install --upgrade pip setuptools
26-
pip install reproschema
28+
pip install git+https://github.com/Remi-Gau/reproschema-py.git@skip
2729
- name: Test with pyshacl
2830
run: |
2931
python scripts/jsonParser.py

‎.github/workflows/validation.yml renamed to ‎.github/workflows/validate_cff.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: validation
2+
name: validation CITATION.cff
33

44
on:
55
pull_request:

‎.remarkrc

+43-11
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,48 @@
33
"preset-lint-markdown-style-guide",
44
"preset-lint-recommended",
55
"remark-gfm",
6-
["lint-no-duplicate-headings", false],
7-
["lint-list-item-indent", "tab-size"],
8-
["lint-emphasis-marker", "consistent"],
9-
["lint-maximum-line-length", 500],
10-
["lint-maximum-heading-length", false],
11-
["lint-no-shortcut-reference-link", false],
12-
["remark-lint-unordered-list-marker-style", "-"],
13-
["lint-no-trailing-spaces"],
14-
["remark-lint-code-block-style", false],
15-
["lint-no-undefined-references", false],
16-
["remark-lint-heading-style", false]
6+
[
7+
"lint-no-duplicate-headings",
8+
false
9+
],
10+
[
11+
"lint-list-item-indent",
12+
"tab-size"
13+
],
14+
[
15+
"lint-emphasis-marker",
16+
"consistent"
17+
],
18+
[
19+
"lint-maximum-line-length",
20+
500
21+
],
22+
[
23+
"lint-maximum-heading-length",
24+
false
25+
],
26+
[
27+
"lint-no-shortcut-reference-link",
28+
false
29+
],
30+
[
31+
"remark-lint-unordered-list-marker-style",
32+
"-"
33+
],
34+
[
35+
"lint-no-trailing-spaces"
36+
],
37+
[
38+
"remark-lint-code-block-style",
39+
false
40+
],
41+
[
42+
"lint-no-undefined-references",
43+
false
44+
],
45+
[
46+
"remark-lint-heading-style",
47+
false
48+
]
1749
]
1850
}

‎docs/FAQ.md

+197-12
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,234 @@
11
# FAQ
22

3+
## Reproschema
34
<!--
4-
## Why should I use ReproSchema?
5+
### Why should I use ReproSchema?
56
67
**🛠 Work in progress 🛠**
78
8-
## Who is ReproSchema for?
9+
### Who is ReproSchema for?
910
1011
**🛠 Work in progress 🛠**
1112
12-
## How can I know if a certain property is supported by ReproSchema?
13+
### How can I know if a certain property is supported by ReproSchema?
1314
1415
**🛠 Work in progress 🛠**
1516
16-
## How can I add a property to my schema?
17+
### How can I add a property to my schema?
1718
1819
**🛠 Work in progress 🛠**
1920
20-
## How are these assessments licensed?
21+
### How are these assessments licensed?
2122
2223
**🛠 Work in progress 🛠**
2324
24-
## How can I contribute to the project?
25+
### How can I contribute to the project?
2526
2627
**🛠 Work in progress 🛠**
2728
28-
## An assessment tool I regularly use is not supported by ReproSchema: how can I add it?
29+
### An assessment tool I regularly use is not supported by ReproSchema: how can I add it?
2930
3031
**🛠 Work in progress 🛠**
3132
-->
3233

33-
## How can I visualize the schema for a `protocol` or an `activity`?
34+
### How can I visualize the schema for a `protocol` or an `activity`?
3435

3536
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).
3637

37-
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:
38+
If you just want to view a protocol or activity you are developing using the `reproschema-ui`,
39+
you can pass the URL of the schema to the `url` query parameter like this:
3840

3941
```https://schema.repronim.org/ui/#/?url=url-to-your-schema```
4042

41-
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:
43+
If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema.
44+
For example, our demo protocol can be accessed at this URL:
4245

4346
[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)
4447

45-
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:
48+
But to get access to the raw content of that file you must click on the `Raw` button
49+
once you have opened that page on github that will open this URL:
4650

4751
[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).
4852

49-
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).
53+
If you want to visualize the graph represented by the JSON-LD file,
54+
we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld).
55+
56+
57+
### Which assessments tools will/are supporting this standard?
58+
59+
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).
60+
61+
If you want to see those different tools in action using our user interface,
62+
you can explore them on [schema.repronim.org/](https://schema.repronim.org/rl/).
63+
64+
The ReproSchema is also used to develop a checklist to [improve methods and results reporting in neuroimaging](https://github.com/ohbm/cobidas).
65+
66+
67+
## Linked data and semantic web
68+
69+
## What is the semantic web?
70+
71+
When you request access to a certain document by clicking on a hyperlink,
72+
the computer will give a visual rendering of the html code of this document.
73+
But computer used to do that in pretty "silly" fashion:
74+
it would give you a human-readable version of the content,
75+
but the computer would not make the distinction if a certain element in the webpage
76+
(for example a paragraph) was referring to a person or a place or a song.
77+
78+
What the semantic wed allows is to "inject" additional information into a webpage
79+
so that a machine can know what certain elements are about (e.g "*this image is about a cat.*")
80+
or how they are linked to other elements (on the same page or somewhere else on the web).
81+
The tagged content of a webpage thus acquires "meaning" from the point of view of the computer,
82+
making the semantic content of the code machine-readable.
83+
84+
#### More info
85+
86+
- [wikipedia article on the semantic web](https://en.wikipedia.org/wiki/Semantic_Web)
87+
- A short video intro to the semantic web by Manu Sporny:
88+
89+
<iframe width="560" height="315" src="https://www.youtube.com/embed/OGg8A2zfWKg" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
90+
91+
### What is linked data?
92+
93+
#### The theory
94+
95+
The same way that an element in webpage could be given "meaning"
96+
by tagging with extra information about the nature of this element, the same can be done with data.
97+
Hence a given row on a spreadsheet stored somewhere on the web can be tagged
98+
and linked to another piece of data on another website.
99+
100+
"*Linked data is a way to create a network of standards-based machine interpretable data across different documents and Web sites. It allows an application to start at one piece of Linked Data, and follow embedded links to other pieces of Linked Data that are hosted on different sites across the Web.*" [[source](https://w3c.github.io/json-ld-bp/#terminology)]
101+
102+
Linked data has some basic principles behind it ([adapted from wikipedia](https://en.wikipedia.org/wiki/Linked_data)):
103+
104+
- Use Unique Resources identifiers (URI) to name (identify) things.
105+
- Use HTTP URIs so that these things can be looked up.
106+
- Provide useful information about what a name identifies when it's looked up.
107+
- Refer to other things using their HTTP URI-based names when publishing data on the Web.
108+
109+
#### A more concrete example
110+
111+
As things might be be quite abstract, here is a simple example of linked data to help make things more concrete:
112+
113+
```json
114+
{
115+
"@context": "http://schema.org",
116+
"name": "Barack Obama",
117+
"givenName": "Barack",
118+
"familyName": "Obama",
119+
"jobTitle": "44th President of the United States"
120+
}
121+
```
122+
123+
You can see that the file is organised in pairs of `"key": "value"`.
124+
The `@context` gives you the base URL of the website where you can find more information
125+
about the different properties of this piece of data.
126+
127+
What follows (`name`, `givenNAme`, `familyName`, ...) are the actual properties about this data
128+
and in front of it the values that this data takes for each property (in this case: "Barack Obama", "Barack", "Obama").
129+
130+
Now go and look up what is hiding behind one of those property
131+
by going to the URL made of the **base URL + the property name**, for example [https://schema.org/familyName](https://schema.org/familyName).
132+
This is the HTTP URI of `familyName` and this gives you a description of the `familyName` property.
133+
134+
Well "*So what?*" you might say.
135+
Well it also tells you which type of data this property it can be applied to: in this case, the `Person` type (see its description [here](https://schema.org/Person)).
136+
So even though, we never wrote anywhere explicitly that this data describes a person,
137+
a computer able to parse that piece of linked data above would "know" this.
138+
139+
#### More info
140+
141+
- Here is [a TED talk](https://www.ted.com/talks/tim_berners_lee_the_next_web) by Tim Berners-Lee on linked data.
142+
- A short video intro to linked data by Manu Sporny:
143+
144+
<iframe width="560" height="315" src="https://www.youtube.com/embed/4x_xzT5eF5Q" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
145+
146+
### What is JSON-LD?
147+
148+
#### What is JSON?
149+
150+
OK before we go for JSON-LD, let's start with JSON. JSON stands for JavaScript Object Notation
151+
and is just a specific format for a text file.
152+
This type of text file is very often used by website when they need to transmit information to one another.
153+
154+
If you want to see an example of how this works, here is [dummy example](http://dummy.restapiexample.com/api/v1/employees) of the response to a request made by one website to another about a list of employees.
155+
By default the output of this dummy example is presented in a way that is more pleasing to the human eye,
156+
but if you click on `Raw Data`, you will see the raw unformatted JSON file that was returned by the website.
157+
Copy-paste in a text editor, it should like the big ugly and scary one-liner below that we, mere mortals,
158+
have no idea what to do with, but that a computer has no problem making sense of.
159+
160+
<!-- **Insert image ???** -->
161+
162+
```json
163+
164+
{"status":"success","data":[{"id":"1","employee_name":"Tiger Nixon","employee_salary":"320800","employee_age":"61","profile_image":""},{"id":"2","employee_name":"Garrett Winters","employee_salary":"170750","employee_age":"63","profile_image":""},{"id":"3","employee_name":"Ashton Cox","employee_salary":"86000","employee_age":"66","profile_image":""},{"id":"4","employee_name":"Cedric Kelly","employee_salary":"433060","employee_age":"22","profile_image":""},{"id":"5","employee_name":"Airi Satou","employee_salary":"162700","employee_age":"33","profile_image":""},{"id":"6","employee_name":"Brielle Williamson","employee_salary":"372000","employee_age":"61","profile_image":""},{"id":"7","employee_name":"Herrod Chandler","employee_salary":"137500","employee_age":"59","profile_image":""},{"id":"8","employee_name":"Rhona Davidson","employee_salary":"327900","employee_age":"55","profile_image":""},{"id":"9","employee_name":"Colleen Hurst","employee_salary":"205500","employee_age":"39","profile_image":""},{"id":"10","employee_name":"Sonya Frost","employee_salary":"103600","employee_age":"23","profile_image":""},{"id":"11","employee_name":"Jena Gaines","employee_salary":"90560","employee_age":"30","profile_image":""},{"id":"12","employee_name":"Quinn Flynn","employee_salary":"342000","employee_age":"22","profile_image":""},{"id":"13","employee_name":"Charde Marshall","employee_salary":"470600","employee_age":"36","profile_image":""},{"id":"14","employee_name":"Haley Kennedy","employee_salary":"313500","employee_age":"43","profile_image":""},{"id":"15","employee_name":"Tatyana Fitzpatrick","employee_salary":"385750","employee_age":"19","profile_image":""},{"id":"16","employee_name":"Michael Silva","employee_salary":"198500","employee_age":"66","profile_image":""},{"id":"17","employee_name":"Paul Byrd","employee_salary":"725000","employee_age":"64","profile_image":""},{"id":"18","employee_name":"Gloria Little","employee_salary":"237500","employee_age":"59","profile_image":""},{"id":"19","employee_name":"Bradley Greer","employee_salary":"132000","employee_age":"41","profile_image":""},{"id":"20","employee_name":"Dai Rios","employee_salary":"217500","employee_age":"35","profile_image":""},{"id":"21","employee_name":"Jenette Caldwell","employee_salary":"345000","employee_age":"30","profile_image":""},{"id":"22","employee_name":"Yuri Berry","employee_salary":"675000","employee_age":"40","profile_image":""},{"id":"23","employee_name":"Caesar Vance","employee_salary":"106450","employee_age":"21","profile_image":""},{"id":"24","employee_name":"Doris Wilder","employee_salary":"85600","employee_age":"23","profile_image":""}]}
165+
166+
```
167+
168+
By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you
169+
1. whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and
170+
1. it will highlight and help you navigate the nested and hierarchical nature of the JSON file.
171+
172+
<!-- **Insert image ???** -->
173+
174+
OK but let's start with a much simpler example of a JSON file,
175+
like the one below which could be the content of JSON file returned by a website when asked about a certain person.
176+
177+
```json
178+
{
179+
"name": "Barack Obama",
180+
"givenName": "Barack",
181+
"familyName": "Obama",
182+
"jobTitle": "44th President of the United States"
183+
}
184+
```
185+
186+
Looks familiar? It is very close to the one we had at the end of the previous FAQ section.
187+
188+
#### From JSON to JSON-LD
189+
190+
Now say you would like to use this JSON file to represent a piece of linked-data.
191+
The only thing you would need to do in this specific case is to provide the `@context`
192+
line we saw before that will give a precise and unambiguous meaning to the following lines.
193+
194+
```json
195+
{
196+
"@context": "http://schema.org",
197+
"name": "Barack Obama",
198+
"givenName": "Barack",
199+
"familyName": "Obama",
200+
"jobTitle": "44th President of the United States"
201+
}
202+
```
203+
204+
🎉 **Congratulations!** 🎉
205+
206+
You now have a valid JSON-LD. If you want to make sure it is valid, you can copy-paste that into the [JSON-LD playground](https://json-ld.org/playground/).
207+
If you to to visualize the "linked" aspect of that data, you can click on the `Visualized` tab
208+
and this will give you a graph where that connects the different nodes (piece of information to one another).
209+
210+
If you want to visualize a more complex graph, we can try that with one of the JSON-LD file that describe one of the `protocols` of the reproschema like the one [here](https://github.com/ReproNim/reproschema/blob/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld).
211+
Actually if you want to test get the raw content of the file you should click on `Raw`.
212+
You can then either use the raw content of the file or the URL of this raw file which should be something like:
213+
214+
```text
215+
https://raw.githubusercontent.com/ReproNim/reproschema/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld
216+
```
217+
218+
directly into the [JSON-LD playground](https://json-ld.org/playground/) to see whether it is a valid JSON-LD and how the different elements are connected.
219+
220+
#### More info
221+
222+
- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration)
223+
but it is good to know that it is out there in case you eventually need to look something up
224+
- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD:
225+
226+
<iframe width="560" height="315"
227+
src="https://www.youtube.com/embed/vioCbTo3C-4" frameborder="0"
228+
allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
229+
</iframe>
230+
231+
<iframe width="560" height="315"
232+
src="https://www.youtube.com/embed/UmvWk_TQ30A" frameborder="0"
233+
allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
234+
</iframe>

0 commit comments

Comments
 (0)