docs: Reorganize documentation for clarity and maintainability (#101)

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.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

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 <input_dir_path> <output_csv_filename>
-```
-
-- `<input_dir_path>`: 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 `<input_dir_path>`.
-- `<output_csv_filename>`: 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.

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.

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.

docs/cli_usage.md renamed to docs/user_guide/cli_usage.md

@@ -0,0 +1,3 @@
+# User Guide
+
+This section provides a detailed guide to using the `reproschema` command-line interface (CLI).

docs/user_guide/index.md

@@ -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