[DOC] Update documentation #399

Remi-Gau · 2020-06-30T12:37:36Z

To-do / TOC

INFRA

setup automatic deploy of the mkdocs when the master branch is updated

Related issues or PR

Primarily in this issue but see also:

UI documentation

update readme (see here) - PR needs review.

Remi-Gau · 2020-06-30T21:49:19Z

@satra @sanuann

There is still much to do but maybe you can already have a look at this and make sure things are on good track in terms of content / style / tone.

Remi-Gau · 2020-07-01T08:13:25Z

@satra @sanuann

Thinking about to give an overview of the project, would it make sense to have an OSF project to help do that as OSF allows to have project components and have each of them track a github repo.

This is what I did for the COBIDAS (see here: https://osf.io/anvqy/) and I could try to do the same with the Reproschema.

Remi-Gau · 2020-07-01T08:14:44Z

Other doc related issue:

This PR on the UI "doc" needs reviewing : ReproNim/reproschema-ui#148

satra · 2020-07-01T11:12:10Z

@Remi-Gau - i think i want to stay with the docs controlling the narrative on reproschema for now before creating an OSF project. perhaps in the future, but at this point, i think github is fine.

Remi-Gau · 2020-07-01T12:02:12Z

@Remi-Gau - i think i want to stay with the docs controlling the narrative on reproschema for now before creating an OSF project. perhaps in the future, but at this point, i think github is fine.

okidoki I am cool with that. :-)

satra · 2020-07-17T18:33:33Z

@Remi-Gau - whenever you get a chance, it would great if you can merge the PR i sent to your repo.

Remi-Gau · 2020-07-17T21:00:09Z

@Remi-Gau - whenever you get a chance, it would great if you can merge the PR i sent to your repo.

@satra
I had missed this. Thanks for pinging me. Will have a look during the weekend.

Remi-Gau · 2020-07-26T08:18:34Z

I had worked on trying to make a small visualization of how the schema would map onto a "pen and paper" version to help people wrap their head around it.

This is obviously a draft.

@sanuann @satra
What do you think? Bad idea? Good idea? What needs to be added/changed/removed ?

satra · 2020-07-26T12:17:09Z

@Remi-Gau - i did open the svg to edit and then decided i had a few other things to address first here are some thoughts that crossed my mind.

the left panel is a github repo. and it can show a protocol and some activities that are a local and some activities that come from a reusable library. in terms of structure, i would drop the context vs schema thing and just say schema (see the text hierarchy diagram under the schema page).
for a library activity we could show the paper and pencil image and indicate that the content is now in the library.
the ui part i like, but i wanted to show that the schema could be rendered through multiple UIs (reproschema-ui, mindlogger, etc.,.)

btw, i've just released 1.0.0-rc1 and my hope is that we can get any updates to the documentation merged in before the 1.0.0 release (say over the next two weeks).

Remi-Gau · 2020-07-26T12:33:25Z

1. the left panel is a github repo. and it can show a protocol and some activities that are a local and some activities that come from a reusable library.

Agreed: will try to see how this can be visualized "easily".

in terms of structure, i would drop the context vs schema thing and just say schema (see the text hierarchy diagram under the schema page).

Agreed I think I did start working on this in the pre-historic times of this repo when we still had the context files. Will drop that.

2. for a library activity we could show the paper and pencil image and indicate that the content is now in the library.

Agreed.

3. the ui part i like, but i wanted to show that the schema could be rendered through multiple UIs (reproschema-ui, mindlogger, etc.,.)

Are you referring to this one?
ReproNim/reproschema-ui#4

btw, i've just released 1.0.0-rc1 and my hope is that we can get any updates to the documentation merged in before the 1.0.0 release (say over the next two weeks).

Woohoo ! 🤞

Remi-Gau · 2020-07-26T12:36:59Z

Oh actually I could make:

a figure to illustrate the example in the reproschema repo
another one showing how you can pull activities from the library.

Or would that be too much?

satra · 2020-07-26T12:48:55Z

perhaps before making the figure (or alongside it), creating the doc section that describes how you can create your own protocol. what are the bare bones requirements (of structuring the repo - see the demo-protocol repo), and what tools (or soon to be available tools) you can use.

Are you referring to this one?
ReproNim/reproschema-ui#4

acutally no just the right part of the figure you posted earlier.

Oh actually I could make:

a figure to illustrate the example in the reproschema repo
another one showing how you can pull activities from the library.

i would say one figure should be sufficient. instead of the example in the reproschema repo, which is more for expanding and illustrating test cases, perhaps use the demo-protocol repo. the demo-protocol repo should really simplify itself to demonstrating reproschema rather than a specific study (current scenario). for example, here are local new activities vs remote activities. in this local activity we are creating new items but also reusing existing items and so on. and i think this is the sentiment that has to come across in the figure.

Remi-Gau · 2020-08-23T07:47:41Z

@satra @sanuann

Finally took some time to start working on a how you can create your own protocol page.

I sort of took the use-case of someone starting from scratch and I try to assume no prior knowledge on git and github.

If you have time to have a look let me know what you think.

Still need to do:

creating an new activity
- creating new items
introducing tools for json validation
introducing reproschema-py for validation

One idea that we was thrown around was to create a template repo, no? To help providing the bare-bone folder structure and infrastructure to create a standalone app, no?

Remi-Gau · 2020-08-23T13:38:38Z

Another idea: would it make sense to have a draft pull request on the library for a new activity where members of the community who want to try to contribute.

satra · 2020-08-23T15:41:27Z

@Remi-Gau - thanks for this - looks great. i think this is the start of great walkthrough. and it's important that people understand the structure even if they end up using more automated tools.

yes. we should definitely create a starter template for those who want to do by hand.

a section that would be good to add is how to fix the references so that any usage/reference is fixed using github checksums and ensure relative paths within an activity.

ps. on to dreaming, the same thing should be generated by a future CLI option:

reproschema protocol --name <protocol> --init
reproschema protocol --name <protocol> --add <activity1> <activity2>
reproschema protocol --name <protocol> --delete <activity1>
reproschema protocol --name <protocol> --list
reproschema library --search "string"  # return urls of relevant activities and items

where the <activityN> can either be a string for a new activity or a remote url for reusing a reproschema library activity. :)

Remi-Gau · 2020-08-23T16:08:38Z

I like your dreams 😍

Actually I think I am actually going to break this part of the doc in several pages because I already anticipate there will be a lot of scrolling otherwise.

- stub for creating activities and items - add some tips referring to CI and how to use valueConstraints

Remi-Gau · 2020-08-25T09:09:53Z

updating figure (see above)
add link to repronim webinar on reproschema

I started adding some tips for validation and using CI.

Also adding some TODOs in comments for future-me.

Sorry if the way the doc grows is not the most linear: I am adding things also as a way for me to takes notes while using some "new" aspects of the reproschema.

- expand on activity creation and tips - start creating page for translation - pointers to items for collecting demographic info

Remi-Gau · 2020-09-04T07:12:41Z

In the schema structure:

explain what terms have camelCase and which ones have PascalCase (multipleChoice vs ResponseOption)
the current link in that page give 404 (eg. https://schema.repronim.org/ResponseOption)
give some info on how to "read" some of those "definitions" (see below)
The following will be more useful to the users if they are sure what rangeIncludes and domainIncludes mean

        {
            "@id": "schema:value",
            "schema:domainIncludes": {
                "@id": "reproschema:Choice"
            },
            "schema:rangeIncludes": [
                {
                    "@id": "reproschema:Skipped"
                },
                {
                    "@id": "reproschema:DontKnow"
                }
            ]
        }

satra · 2022-04-16T14:13:25Z

@Remi-Gau - thanks for putting this together. i think this will be good to resurrect and finish. @Rahul-Brito may be able to review this and add any additional materials.

Remi-Gau · 2022-04-16T15:10:51Z

Happy to wrap this one up.
Maybe a mini-dockathon so we can all synch up on this?

satra · 2022-05-05T14:07:30Z

@Rahul-Brito - can you coordinate a docathon around this ?

Rahul-Brito · 2022-05-20T21:03:23Z

Hi @Remi-Gau so sorry for not replying earlier. I'm a new graduate student in Satra's lab, nice to meet you. 've been trying to prioritize all the things I want to do/need to do and replying to this has been on the back of my mind for a little.

My understanding is we want to get a nice, easy-to-implement "hello world" reproschma repo up and running? If so, that sounds great to me. I have run into issues getting my own started, even with the existing documentation we have, and I can't always tell if this is user error, dependency error, etc.

Let me know if I misunderstand!

Also, how does a dockathon compare to a hackaton :D.

Anyways, let me know! Perhaps next week or the week after we can set something up. I will be sure to be much more responsive as well.

Remi-Gau · 2022-05-21T05:52:56Z

hey @Rahul-Brito

nice to e-meet you

I suspect that finishing up all the unticked boxes in this PR could be a start as well for some doc

And a dockathon is litteraly a hackaton but where participants only work on the documentation of a project.

So 2 or 3 days where we don't write code but instead we write code comments, doc for developpers, tutorials, demos, FAQ...

Remi-Gau · 2024-03-20T19:58:32Z

mkdocs.yml

+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences


adds syntax highlithing

Remi-Gau · 2024-03-20T20:34:18Z

merge conflicts fixed

moved all my stuff in a "tutorial" section

this will probably need a "refactoring"

Also need to make sure that people following the tuto would actually result in something valid: almost tempted to say that all the code snippets should actually be executable to make sure they stay valid.

Also not sure how the "linkMLification" will affect the doc.

yibeichan · 2024-05-10T15:04:42Z

we're going to merge then clean up duplicates

satra mentioned this pull request Jul 7, 2020

update readme #378

Closed

satra changed the base branch from refactor-1.0 to master July 18, 2020 15:33

satra closed this Jul 18, 2020

satra reopened this Jul 18, 2020

satra mentioned this pull request Jul 19, 2020

Add schema structure and properties to docs #414

Merged

Remi-Gau closed this Jul 26, 2020

Remi-Gau force-pushed the remi-documentation branch from 56d169f to a639390 Compare July 26, 2020 07:22

add more info on schema description

b4e2fd8

Remi-Gau reopened this Jul 26, 2020

add a how to create a protocol page

de80928

splitting tutorial in several pages

b387613

- stub for creating activities and items - add some tips referring to CI and how to use valueConstraints

Remi-Gau added 2 commits August 30, 2020 11:35

update doc

4a59c0e

- expand on activity creation and tips - start creating page for translation - pointers to items for collecting demographic info

[DOC] use demographics to show how to reuse items

74310e6

fix demographics

fa04451

Remi-Gau mentioned this pull request Nov 1, 2020

Create your own app: “a test run for the documentation” Remi-Gau/eCobidas#177

Closed

3 tasks

Remi-Gau mentioned this pull request Apr 14, 2022

"hello world" (ReproSchema for Dummies) instructions? ReproNim/demo-protocol#21

Closed

Merge branch 'master' into remi-documentation

777e5a7

Remi-Gau changed the title ~~[WIP] Documentation~~ [DOC] Update documentation Mar 20, 2024

Remi-Gau added 4 commits March 20, 2024 15:37

Merge remote-tracking branch 'upstream/master' into remi-documentation

3e7b69c

move files into a different section

4f0bc46

revert

c859504

add syntax highlighting

b435918

Remi-Gau commented Mar 20, 2024

View reviewed changes

fa04451 fix demographics

d51b369

Remi-Gau marked this pull request as ready for review March 20, 2024 20:31

yibeichan merged commit 2f1211f into ReproNim:master May 10, 2024
1 check passed

Remi-Gau deleted the remi-documentation branch May 10, 2024 20:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] Update documentation #399

[DOC] Update documentation #399

Remi-Gau commented Jun 30, 2020 •

edited

Loading

Remi-Gau commented Jun 30, 2020

Remi-Gau commented Jul 1, 2020

Remi-Gau commented Jul 1, 2020

satra commented Jul 1, 2020

Remi-Gau commented Jul 1, 2020

satra commented Jul 17, 2020

Remi-Gau commented Jul 17, 2020

Remi-Gau commented Jul 26, 2020

satra commented Jul 26, 2020

Remi-Gau commented Jul 26, 2020

Remi-Gau commented Jul 26, 2020

satra commented Jul 26, 2020

Remi-Gau commented Aug 23, 2020 •

edited

Loading

Remi-Gau commented Aug 23, 2020

satra commented Aug 23, 2020

Remi-Gau commented Aug 23, 2020

Remi-Gau commented Aug 25, 2020 •

edited

Loading

Remi-Gau commented Sep 4, 2020

satra commented Apr 16, 2022

Remi-Gau commented Apr 16, 2022

satra commented May 5, 2022

Rahul-Brito commented May 20, 2022

Remi-Gau commented May 21, 2022

Remi-Gau Mar 20, 2024

Remi-Gau commented Mar 20, 2024

yibeichan commented May 10, 2024

[DOC] Update documentation #399

[DOC] Update documentation #399

Conversation

Remi-Gau commented Jun 30, 2020 • edited Loading

To-do / TOC

INFRA

Related issues or PR

UI documentation

Remi-Gau commented Jun 30, 2020

Remi-Gau commented Jul 1, 2020

Remi-Gau commented Jul 1, 2020

satra commented Jul 1, 2020

Remi-Gau commented Jul 1, 2020

satra commented Jul 17, 2020

Remi-Gau commented Jul 17, 2020

Remi-Gau commented Jul 26, 2020

satra commented Jul 26, 2020

Remi-Gau commented Jul 26, 2020

Remi-Gau commented Jul 26, 2020

satra commented Jul 26, 2020

Remi-Gau commented Aug 23, 2020 • edited Loading

Remi-Gau commented Aug 23, 2020

satra commented Aug 23, 2020

Remi-Gau commented Aug 23, 2020

Remi-Gau commented Aug 25, 2020 • edited Loading

Remi-Gau commented Sep 4, 2020

satra commented Apr 16, 2022

Remi-Gau commented Apr 16, 2022

satra commented May 5, 2022

Rahul-Brito commented May 20, 2022

Remi-Gau commented May 21, 2022

Remi-Gau Mar 20, 2024

Choose a reason for hiding this comment

Remi-Gau commented Mar 20, 2024

yibeichan commented May 10, 2024

Remi-Gau commented Jun 30, 2020 •

edited

Loading

Remi-Gau commented Aug 23, 2020 •

edited

Loading

Remi-Gau commented Aug 25, 2020 •

edited

Loading