Merge pull request #125 from Remi-Gau/mkdoc

[ENH] add mkdoc

.github/workflows/publishdocs.yaml

@@ -0,0 +1,19 @@
+---
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+    - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout master
+      uses: actions/checkout@v4
+
+    - name: Deploy docs
+      uses: mhausenblas/mkdocs-deploy-gh-pages@master
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -50,10 +50,4 @@ If you want to join this project, please check out our [INCF Working Group](http
 
 ARTEM-IS is developed by an [INCF working group](https://www.incf.org/sig/incf-working-group-artem), in partnership with [eCOBIDAS](https://www.incf.org/sig/incfohbm-working-group-checklists-transparent-methods-reporting-neuroscience-ecobidas).
 
-A centralized list of the people who contributed to this project can be found [here](https://osf.io/ut9pc/).
-
-## License
-
-The template is licensed CC-BY-4.0
-
-(c) 2020 INCF Working Group on ARTEMIS
+A centralized list of the people who contributed to this project can be found [here](https://osf.io/ut9pc/).

mkdocs.yml

@@ -0,0 +1,70 @@
+# See https://www.mkdocs.org/ for more info on the config
+---
+site_name: ARTEM-IS
+repo_url: https://github.com/INCF/artem-is
+
+nav:
+- ARTEM-IS: index.md
+- Details:
+  - Scope: details/scope.md
+- lexicon: lexicon.md
+- links: links.md
+- Contributors: CONTRIBUTING.md
+- Release notes: CHANGELOG.md
+
+theme:
+  name: material
+  favicon: images/favicon/favicon-32x32.png
+  logo: images/logos/logo.png
+  features:
+  - navigation.top
+  - content.action.edit
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+  palette:
+    # Palette toggle for automatic mode
+  - media: (prefers-color-scheme)
+    toggle:
+      icon: material/brightness-auto
+      name: Switch to light mode
+    # Palette toggle for light mode
+  - media: '(prefers-color-scheme: light)'
+    scheme: default
+    toggle:
+      icon: material/brightness-7
+      name: Switch to dark mode
+    # Palette toggle for dark mode
+  - media: '(prefers-color-scheme: dark)'
+    scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to system preference
+
+copyright: Copyright &copy; INCF Working Group on ARTEMIS - <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>
+
+edit_uri: edit/main/src/
+
+extra:
+  generator: false
+  social:
+  # X / Twitter
+  # - icon: fontawesome/brands/twitter
+  #   link: https://twitter.com/????
+  - icon: fontawesome/brands/github
+    link: https://github.com/INCF/artem-is.git
+  #  Google group ?
+  # - icon: fontawesome/brands/google
+  #   link: https://groups.google.com/g/????
+
+markdown_extensions:
+- toc:
+    anchorlink: true
+- pymdownx.superfences
+
+plugins:
+- search
+
+docs_dir: src
+
+use_directory_urls: false

requirements.txt

@@ -1,3 +1,14 @@
+# documentation deployment
+mkdocs>=1.1
+mkdocs-material>=5.4
+# checklist maintenance
 gdown
 pandas
 rich
+# linting, styling, validation
+black
+flake8
+cffconvert
+pre-commit
+sourcery
+

src/CHANGELOG.md

@@ -0,0 +1 @@
+# Release notes

CONTRIBUTING.md → src/CONTRIBUTING.md

@@ -27,3 +27,25 @@ It can be triggered manually:
   in the `Conversation` tab.
 
 ![merge](./images/merge.png)
+
+
+## Serve the website locally (on your computer)
+
+### Requirements
+
+- Python
+
+To install all the necessarry packages,
+type the following in a terminal in the root of the repository:
+
+```bash
+pip install -r requirments.txt
+```
+
+### Serve the website
+
+Type the following in a terminal in the root of the repository:
+
+```bash
+mkdocs serve
+```

src/details/scope.md

@@ -0,0 +1 @@
+# Just an example

src/images/favicon/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

src/index.md

@@ -0,0 +1,57 @@
+<!-- comment: landing page for ARTEMIS app -->
+
+<center>
+
+![](https://raw.githubusercontent.com/ohbm/eCOBIDAS/master/images/ARTEMIS_logo.jpg)
+
+</center>
+
+The goal of the ARTEM-IS is to use insights derived from systematic reviews and guidelines for good checklist design to create dynamic and user-friendly web applications which support EEG researchers in creating detailed human- and machine-readable methods summaries. Currently, ARTEM-IS has launched the first of its tools, ARTEM-IS for ERP, which supports describing a simple ERP experiment, including most of its core methodological aspects (study description, experimental design, hardware, data acquisition, pre-processing, measurement, visualisation, additional comments – artemis.incf.org). ARTEM-IS tools for more complex ERP experiments as well as for other subfields of EEG may follow.
+
+## How to use it
+
+1. The web-app is available **[HERE](https://artemis.incf.org/)**.
+2. On the initial page, you can create your account and log in, as well as view a visualization of the basic structure of the information provided in the template.
+3. Once logged in, by clicking `Create` in the top right corner, you can create a new, blank template.
+4. You can navigate a template by using the menu on top and answer the questions corresponding to the study you are reporting on. This is meant to ensure that you have not forgotten any of the essential information during data collection or later in the methods and results parts of your article.
+5. Click `Save` in the top right corner to save any changes.
+6. You can view your own saved templates using `My templates` option. For each template, you have the options to make them publically (in)visible to others, download a human-readable PDF output and download a machine-readable JSON output. All templates are set to private in the beginning.
+7. You can view and download publically available templates by other members using `Browse` menu.
+8. You can upload a previously downloaded (in JSON format) templates to your account using `Upload` menu.
+
+You can find output examples on the [OSF page of this project](https://osf.io/ahp3t/).
+
+## Why this project?
+
+It is well known that choices made during recording, preprocessing and analysis of EEG data can affect study outcomes, making it critical to describe EEG methods and the decision-making process thoroughly and transparently. Transparent methods records would allow not only better reproducibility and replicability of EEG research or a better appraisal of the quality of existing studies, but also provide a better basis for novel research, for example by providing meta-scientists with relevant information on published studies. Researchers new to the field of EEG may especially benefit from transparent and thorough reports of EEG studies, as some of them are not beneficiaries of the decades of knowledge contained in unpublished materials like ‘lab handbooks’ which may be passed down in labs with longer traditions.
+
+Despite this, systematic reviews of reporting practices in the field have shown that journal articles do not meet this goal and that guidelines for writing them better have not resulted in a sufficient improvement to reporting transparency. ARTEM-IS is designed to help with this issue as ARTEM-IS reports contain a level of reporting precision higher than what is typically found in journal articles, which can be used as supplements to a publication, as a memory aid when writing a paper, or as records that allow easier metadata extraction in comparison to verbal descriptions in papers.
+
+### Want to know more ?
+
+Read more about the rationale for this project and the design principles we go by in our **[paper](https://www.sciencedirect.com/science/article/pii/S1053811921009939?via%3Dihub)**, and if you agree support us by signing the **[ARTEM-IS statement](https://osf.io/mf97q/)**.
+
+1. Have a look at our **[project on OSF](https://osf.io/pvrn6/)**.
+2. **Talks and slides** are available [HERE](https://osf.io/ncav8/).
+
+## Get in touch
+
+Want to know more? Have any questions? Something is missing? Send us an [email](mailto:[email protected]).
+
+For occasional updates on the project, join our [mailing list](mailto:[email protected]).
+
+## Want to help?
+
+If you want to join this project, please check out our [INCF Working Group](https://www.incf.org/sig/incf-working-group-artem) and apply for joining it by filling in this [form](https://forms.gle/QHFakdGUQ69QrCYc9).
+
+## Contributors
+
+ARTEM-IS is developed by an [INCF working group](https://www.incf.org/sig/incf-working-group-artem), in partnership with [eCOBIDAS](https://www.incf.org/sig/incfohbm-working-group-checklists-transparent-methods-reporting-neuroscience-ecobidas).
+
+A centralized list of the people who contributed to this project can be found [here](https://osf.io/ut9pc/).
+
+## License
+
+The template is licensed CC-BY-4.0
+
+(c) 2020 INCF Working Group on ARTEMIS

src/links.md

@@ -0,0 +1 @@
+# Links