Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[ENH] add mkdoc #125

Merged
merged 1 commit into from
Nov 17, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/publishdocs.yaml
Original file line number Diff line number Diff line change
@@ -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 }}
397 changes: 397 additions & 0 deletions LICENSE

Large diffs are not rendered by default.

8 changes: 1 addition & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
70 changes: 70 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
@@ -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

3 changes: 0 additions & 3 deletions requirements_dev.txt

This file was deleted.

1 change: 1 addition & 0 deletions src/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Release notes
22 changes: 22 additions & 0 deletions CONTRIBUTING.md → src/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
1 change: 1 addition & 0 deletions src/details/scope.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Just an example
Binary file added src/images/favicon/android-chrome-192x192.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/favicon/android-chrome-512x512.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/favicon/apple-touch-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/favicon/favicon-16x16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/favicon/favicon-32x32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/favicon/favicon.ico
Binary file not shown.
1 change: 1 addition & 0 deletions src/images/favicon/site.webmanifest
Original file line number Diff line number Diff line change
@@ -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"}
File renamed without changes
Binary file added src/images/logos/logo.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/images/logos/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
56 changes: 56 additions & 0 deletions src/images/logos/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
File renamed without changes
File renamed without changes
57 changes: 57 additions & 0 deletions src/index.md
Original file line number Diff line number Diff line change
@@ -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
Empty file added src/lexicon.md
Empty file.
1 change: 1 addition & 0 deletions src/links.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Links
Loading