From 2c8142cb64baf6925fb4a05a9f5b86b57f2b03c5 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 15 Aug 2025 02:38:10 +0000 Subject: [PATCH] docs: Reorganize documentation for clarity and maintainability This commit reorganizes the documentation to improve clarity, reduce duplication, and make it easier to maintain. The key changes are: - The main README.md has been simplified to provide a concise project overview, installation instructions, and a link to the full documentation. - Detailed CLI documentation has been moved from the README.md to a dedicated `docs/user_guide` section. - The `mkdocs.yml` file has been updated to reflect the new, nested documentation structure. - A new `docs/about.md` file has been created to provide information about the documentation's structure. --- README.md | 139 +------------------- docs/about.md | 20 +++ docs/index.md | 20 +-- docs/{ => user_guide}/cli_usage.md | 0 docs/user_guide/index.md | 3 + docs/{ => user_guide}/output2redcap.md | 0 docs/{ => user_guide}/redcap2reproschema.md | 0 docs/{ => user_guide}/reproschema2fhir.md | 0 docs/{ => user_guide}/reproschema2redcap.md | 0 mkdocs.yml | 13 +- 10 files changed, 44 insertions(+), 151 deletions(-) create mode 100644 docs/about.md rename docs/{ => user_guide}/cli_usage.md (100%) create mode 100644 docs/user_guide/index.md rename docs/{ => user_guide}/output2redcap.md (100%) rename docs/{ => user_guide}/redcap2reproschema.md (100%) rename docs/{ => user_guide}/reproschema2fhir.md (100%) rename docs/{ => user_guide}/reproschema2redcap.md (100%) diff --git a/README.md b/README.md index 2e814d6..4a4ab0b 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ # Reproschema Python library and Command Line Interface (CLI) +The `reproschema-py` library provides a Python interface and a command-line tool to work with ReproSchema, a YAML-based framework for creating and managing reproducible research protocols. + +For more information, see the [full documentation](https://ReproNim.github.io/reproschema-py/). + ## Installation reproschema requires Python 3.10+. @@ -10,6 +14,8 @@ reproschema requires Python 3.10+. pip install reproschema ``` +## Developer Guide + ### Developer installation Fork this repo to your own GitHub account, then clone and install your forked repo in the developer mode: @@ -32,136 +38,3 @@ This repo uses pre-commit to check styling. 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. - - -## 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 -``` - -## `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) -``` - -## `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) -``` - -## `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 -``` - -## `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/about.md b/docs/about.md new file mode 100644 index 0000000..0e4beb2 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,20 @@ +# About this documentation + +This section provides information about the structure of this documentation site. + +## Project layout + +The documentation is organized as follows: + + mkdocs.yml # The MkDocs configuration file. + docs/ + index.md # The documentation homepage. + installation.md # Installation instructions. + about.md # Information about this documentation. + user_guide/ + index.md # Introduction to the user guide. + cli_usage.md # General CLI usage. + reproschema2redcap.md # reproschema to REDCap conversion. + redcap2reproschema.md # REDCap to reproschema conversion. + output2redcap.md # output to REDCap conversion. + reproschema2fhir.md # reproschema to FHIR conversion. diff --git a/docs/index.md b/docs/index.md index ed426c0..08a9790 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,9 @@ # 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 reproschema to redcap - redcap2reproschema.md #How to convert from redcap to reproschema - output2redcap.md #How to convert the output into redcap - reproschema2fhir.md #How to convert the reproschema into an FHIR Questionnaire Resource +The `reproschema-py` library provides a Python interface and a command-line tool to work with ReproSchema, a YAML-based framework for creating and managing reproducible research protocols. + +This documentation will guide you through the installation process, explain how to use the command-line interface, and provide information for developers who want to contribute to the project. + +## Getting Started + +If you are new to `reproschema-py`, we recommend starting with the **[Installation](installation.md)** guide, followed by the **[User Guide](user_guide/index.md)** to learn about the available commands. diff --git a/docs/cli_usage.md b/docs/user_guide/cli_usage.md similarity index 100% rename from docs/cli_usage.md rename to docs/user_guide/cli_usage.md diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md new file mode 100644 index 0000000..e4cbfd9 --- /dev/null +++ b/docs/user_guide/index.md @@ -0,0 +1,3 @@ +# User Guide + +This section provides a detailed guide to using the `reproschema` command-line interface (CLI). diff --git a/docs/output2redcap.md b/docs/user_guide/output2redcap.md similarity index 100% rename from docs/output2redcap.md rename to docs/user_guide/output2redcap.md diff --git a/docs/redcap2reproschema.md b/docs/user_guide/redcap2reproschema.md similarity index 100% rename from docs/redcap2reproschema.md rename to docs/user_guide/redcap2reproschema.md diff --git a/docs/reproschema2fhir.md b/docs/user_guide/reproschema2fhir.md similarity index 100% rename from docs/reproschema2fhir.md rename to docs/user_guide/reproschema2fhir.md diff --git a/docs/reproschema2redcap.md b/docs/user_guide/reproschema2redcap.md similarity index 100% rename from docs/reproschema2redcap.md rename to docs/user_guide/reproschema2redcap.md diff --git a/mkdocs.yml b/mkdocs.yml index 969336d..3f337c9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,10 +2,13 @@ site_name: reproschema-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 + - User Guide: + - Introduction: user_guide/index.md + - CLI Usage: user_guide/cli_usage.md + - Reproschema to REDCap: user_guide/reproschema2redcap.md + - REDCap to Reproschema: user_guide/redcap2reproschema.md + - Output to REDCap: user_guide/output2redcap.md + - Reproschema to FHIR: user_guide/reproschema2fhir.md + - About: about.md theme: readthedocs