[REF] refactor documentation

[Remi-Gau]

• follow up on [FIX] misc minor fixes to the documentation #482
  • rebase on master after [FIX] misc minor fixes to the documentation #482 is merged for a cleaner diff
• relates to TODO list to improve documentation #478

What this PR does:

• extracts from the doc any jsonld code blocks and store them in actual jsonld files that can be validated with reproschema-py. The files are then directly "injected" in the documentation. This makes sure that the jsonld presented in the doc is always valid according to the reproschema.
• merge FAQ pages
• remove glossary as most definitions are already part of the schema

[Remi-Gau]

Will try to extend the logic of this PR to extract all files examples from the doc into actual files so their content can be properly validated.

Because the user guide is based on the reproschema-demo-protocol: https://github.com/ReproNim/reproschema-demo-protocol
I wonder if we should not sub-module it into this repo, so file content can directly be "injected" into the doc.

[yibeichan]

@Remi-Gau I finally have some time to think about our overall documentation; here is the plan:
currently we have
User Guide

• Create a research protocol
• Adopt assessments from the library
• Create new assessments for a protocol
• Add a feedback section
• Finalize the protocol
• Toolkit

Tutorial

• Intro
• Create a research protocol
• Creating a new activity
• Tips to make your life easier
• Translate a questionnaire
• Demographic information

We want to change User Guide to something more like a manual, probably we should have one page for each repo (e.g., reproschema, reproschema-library, reproschema-py, reproschema-ui, reproschema-protocol-cookiecutter), where we detail the usage of each repo (currently i can only think of reproschema-library, reproschema-py,reproschema-protocol-cookiecutter)
for tutorials, we can merge Create a research protocol Adopt assessments from the library Create new assessments for a protocol in User Guide with Create a research protocol Creating a new activity in Tutorial
the current Demographic information can be merged into Adopt assessments from the library
the current Intro can be merged into Create a research protocol. if we want, we can write a new Intro

let me know what you think, we can meet and revise the plan, then split the task.

[yibeichan]

Because the user guide is based on the reproschema-demo-protocol: https://github.com/ReproNim/reproschema-demo-protocol I wonder if we should not sub-module it into this repo, so file content can directly be "injected" into the doc.

okay I found myself lost in this sentence, haha. so what do we want to do and what should not do here?

[Remi-Gau]

Will update the top message to explain what the PR does because otherwise future me is lost when he gets back to it

[Remi-Gau]

Validation fails because there is a README.md file in amongst the jsonld files but this should be fixed when ReproNim/reproschema-py#40 is merged.

In the meantime I will run the validation with that branch from my fork.

[yibeichan]

use this branch for validation
https://github.com/djarecka/reproschema-py/tree/ref/linkml

[Remi-Gau]

The user guide points to the demo protocol: if we update the demo protocol the user-guide may be out of synch with the content of the demo protocol repo.

May potentially be good to submodule the demo-protocol and read content directly from there.

[Remi-Gau]

Similarly some of the examples I have generated are based on some of the content from that PR
ReproNim/reproschema-library#60

So once this gets merged, we could use the same strategy of submoduling the library and read jsonld content directly from there: this may also allows us to give a listing of the content of the library as part of the documentation.

[yibeichan]

thank you!! @Remi-Gau i'm gonna merge this one now, once the new context URL is ready, I'll replace them. quick question: I saw all jsonld file has .jsonld extension, is it because we need this extension to help identify which file we want to validate (without .jsonld it would be hard to know which is which)? but in general, we don't add .jsonld in reproschema

[Remi-Gau]

we don't add .jsonld in reproschema

Let me turn the question around: why is it not the case?