diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml new file mode 100644 index 0000000..96b0911 --- /dev/null +++ b/.github/workflows/deploy_mkdocs.yml @@ -0,0 +1,24 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - main + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v2 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme + env: + GITHUB_TOKEN: ${{ secrets.AUTO_TOKEN }} + CUSTOM_DOMAIN: https://repronim.github.io/reproschema-py/ + CONFIG_FILE: mkdocs.yml + EXTRA_PACKAGES: build-base + # GITHUB_DOMAIN: github.myenterprise.com + # REQUIREMENTS: folder/requirements.txt diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..f4a5f97 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +https://repronim.github.io/reproschema-py/ diff --git a/docs/cli_usage.md b/docs/cli_usage.md new file mode 100644 index 0000000..fdd423c --- /dev/null +++ b/docs/cli_usage.md @@ -0,0 +1,30 @@ +## CLI usage + +This package installs `reproschema` Command Line Interface (CLI). + +``` +$ reproschema --help + +$ A client to support interactions with ReproSchema + + To see help for a specific command, run + + reproschema COMMAND --help e.g. reproschema validate --help + +Options: + --version + -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] + Log level name [default: INFO] + --help Show this message and exit. + +Commands: + convert Converts a path to a different format, jsonld,... + create + migrate Updates to a new reproschema version + redcap2reproschema Converts REDCap CSV files to Reproschema format. + reproschema2redcap Converts reproschema protocol to REDCap CSV format. + serve + validate Validates if the path has a valid reproschema format + reproschema2fhir Generates FHIR questionnaire resources from reproschema activities + output2redcap Generates redcap csv given the audio and survey data from reproschema ui +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..08bd94b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +# Welcome to Reproschema-py + +For full documentation visit [Reproschema-py](https://github.com/ReproNim/reproschema-py). +reproschema requires Python 3.10+ + +## Project layout + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + installation.md #A tutorial for installation. + cli_usage.md #Notes on CLI usage + reproschema2redcap.md #How to convert from resproschema to redcap + redcap2reproschema.md #How to convert from redcap to reproscehma + output2redcap.md #How to convert the output into redcap + reproschema2fhir.md #How to convert the reproschema into an FHIR Questionnaire Resource diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..c250651 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,25 @@ +## Installation + +Use the following command to install reproschema: + +``` +pip install reproschema +``` + +### Developer installation + +Fork this repo to your own GitHub account, then clone and install your forked repo in the developer mode: + +``` +git clone https://github.com//reproschema-py.git +cd reproschema-py +pip install -e . +``` +#### Style +This repo uses pre-commit to check styling. +- Install pre-commit with pip: `pip install pre-commit` +- In order to use it with the repository, you have to run `run pre-commit install` in the root directory the first time you use it. + +When pre-commit is used, you may have to run git commit twice, +since pre-commit may make additional changes to your code for styling and will +not commit these changes by default. diff --git a/docs/output2redcap.md b/docs/output2redcap.md new file mode 100644 index 0000000..b0fa496 --- /dev/null +++ b/docs/output2redcap.md @@ -0,0 +1,10 @@ +## `output2redcap` +The `output2redcap` function is designed to process the output from reproschema-ui into a REDCap CSV file as seen [here](reproschema/example/redcap). + + +### CLI Usage + +The `output2redcap` function has been integrated into a CLI tool, use the following command: +```bash +reproschema output2redcap ./path/to/your_reproschema-ui_files ./path/to/directory_you_want_to_save_output +``` diff --git a/docs/redcap2reproschema.md b/docs/redcap2reproschema.md new file mode 100644 index 0000000..6234bcf --- /dev/null +++ b/docs/redcap2reproschema.md @@ -0,0 +1,45 @@ +## `redcap2reproschema` +The `redcap2reproschema` function is designed to process a given REDCap CSV file and YAML configuration to generate the output in the reproschema format. + +### Prerequisites +Before the conversion, ensure you have the following: + +**YAML Configuration File**: + - Download [templates/redcap2rs.yaml](templates/redcap2rs.yaml) and fill it out with your protocol details. + +### YAML File Configuration +In the `templates/redcap2rs.yaml` file, provide the following information: + +- **protocol_name**: A unique identifier for your protocol. Use underscores for spaces and avoid special characters. +- **protocol_display_name**: Name that will appear in the application. +- **protocol_description**: A brief description of your protocol. +- **redcap_version**: Version of your redcap file (you can customize it). + +Example: +```yaml +protocol_name: "My_Protocol" +protocol_display_name: "Assessment Protocol" +protocol_description: "This protocol is for assessing cognitive skills." +redcap_version: "X.XX.X" +``` +### CLI Usage + +The `redcap2reproschema` function has been integrated into a CLI tool, use the following command: +```bash +reproschema redcap2reproschema path/to/your_redcap_data_dic.csv path/to/your_redcap2rs.yaml +``` + +Optionally you can provide a path to the output directory (default is the current directory) by adding the option: `--output-path PATH` +### Python Function Usage + +You can also use the `redcap2reproschema` function from the `reproschema-py` package in your Python code. + +```python +from reproschema import redcap2reproschema + +csv_path = "path-to/your_redcap_data_dic.csv" +yaml_path = "path-to/your_redcap2rs.yaml" +output_path = "path-to/directory_you_want_to_save_output" + +redcap2reproschema(csv_file, yaml_file, output_path) +``` diff --git a/docs/reproschema2fhir.md b/docs/reproschema2fhir.md new file mode 100644 index 0000000..7a7529c --- /dev/null +++ b/docs/reproschema2fhir.md @@ -0,0 +1,11 @@ +## `reproschema2fhir` +The `reproschema2fhir` function is designed to convert reproschema activities and items into a FHIR Questionnaire resource as seen [here](reproschema/example/fhir). + +### CLI Usage + +The `reproschema2fhir` function has been integrated into a CLI tool, use the following command: +```bash +reproschema reproschema2fhir ./path/to/your_reproschema_activities ./path/to/directory_you_want_to_save_output +``` +### Notes +1. The script requires an active internet connection to access the GitHub repository. diff --git a/docs/reproschema2redcap.md b/docs/reproschema2redcap.md new file mode 100644 index 0000000..3b35ee3 --- /dev/null +++ b/docs/reproschema2redcap.md @@ -0,0 +1,31 @@ +## `reproschema2redcap` + +### CLI Usage + +You can use this feature directly from the command line. To convert ReproSchema protocol to REDCap CSV format, use the following command + +``` +reproschema reproschema2redcap +``` + +- ``: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands: + ```bash + git clone https://github.com/ReproNim/reproschema-demo-protocol.git + cd reproschema-demo-protocol + pwd + ``` + In this case, the output from `pwd` (which shows your current directory path) should be your ``. +- ``: The name of the output CSV file where the converted data will be saved. + +### Python Function Usage + +You can also use the `reproschema2redcap` function from the `reproschema-py` package in your Python code. + +```python +from reproschema import reproschema2redcap + +input_dir_path = "path-to/reproschema-demo-protocol" +output_csv_filename = "output.csv" + +reproschema2redcap(input_dir_path, output_csv_filename) +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..bdcc7c0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,11 @@ +site_name: reporschema-py +nav: + - Home: index.md + - Installation: installation.md + - CLI Usage: cli_usage.md + - Converting from reproschema to redcap: reproschema2redcap.md + - Converting from redcap to reproschema: redcap2reproschema.md + - Converting the output into redcap: output2redcap.md + - Converting the reproschema into an FHIR Questionnaire Resource: reproschema2fhir.md + +theme: readthedocs