📝 Update README and docs structure

Author: sayalaruano

README.md

@@ -36,7 +36,11 @@ An overview of the VueGen workflow is shown in the figure below:
 
 ![VueGen Abstract](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_graph_abstract.png)
 
-Also, the class diagram for the project is presented below to illustrate the architecture and relationships between classes:
+We created a schema diagram to illustrates the structure of the configuration file and the relationships between its elements:
+
+![VueGen Schema Diagram](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_schema_diagram.png)
+
+Also, the class diagram for the project's current version is presented below to show the architecture and relationships between classes:
 
 ![VueGen Class Diagram](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_classdiagram_noattmeth.png)
 
@@ -59,9 +63,11 @@ pip install vuegen
 
 You can also install the package for development by cloning this repository and running the following command:
 
+> [!WARNING]
+> We assume you are in the root directory of the cloned repository when running this command. Otherwise, you need to specify the path to the `vuegen` directory.
+
 ```bash
-pip install -e path/to/vuegen # specify location
-pip install -e . # in case your pwd is in the vuegen directory
+pip install -e .
 ```
 
 ### Conda
@@ -98,12 +104,12 @@ If you prefer not to install VueGen on your system, a pre-configured Docker cont
 
 ### Nextflow and nf-core
 
-VueGen is also available as a [nf-core][nfcore] module, customised for compatibility with the [Nextflow][nextflow] environment. This module is designed to automate report generation from outputs produced by other modules, subworkflows, or pipelines. You can read the offical documentation for the nf-core module [here](nf-vuegen-nf-core). Also, the source code and detailed documentation are available in the [nf-VueGen repository][nf-vuegen].
+VueGen is also available as a [nf-core][nfcore] module, customised for compatibility with the [Nextflow][nextflow] environment. This module is designed to automate report generation from outputs produced by other modules, subworkflows, or pipelines. You can read the offical documentation for the nf-core module [here][nf-vuegen-nf-core]. Also, the source code and additional details are available in the [nf-VueGen repository][nf-vuegen].
 
 ## Execution
 
 > [!IMPORTANT]
-> Here we use the `Earth_microbiome_vuegen_demo_notebook` [directory][emp-dir] and the `Earth_microbiome_vuegen_demo_notebook.yaml` [configuration file][emp-config] as examples, which are available in the `docs/example_data` and `docs/example_config_files` folders, respectively. Make sure to clone this reposiotry to access these contents, or use your own directory and configuration file.
+> Here we use the `Earth_microbiome_vuegen_demo_notebook` [directory][emp-dir] and the `Earth_microbiome_vuegen_demo_notebook.yaml` [configuration file][emp-config] as examples, which are available in the `docs/example_data` and `docs/example_config_files` folders, respectively. Make sure to clone the VueGen's GitHub reposiotry to access these contents, or use your own directory and configuration file.
 
 Run VueGen using a directory with the following command:
 
@@ -116,18 +122,20 @@ vuegen --directory docs/example_data/Earth_microbiome_vuegen_demo_notebook --rep
 
 ### Folder structure
 
-Your input directory must follow a **nested folder structure**, where first-level folders are treated as **sections** and second-level folders as **subsections**, containing the components (plots, tables, networks, Markdown text, and HTML files).
+Your input directory should follow a **nested folder structure**, where first-level folders are treated as **sections** and second-level folders as **subsections**, containing the components (plots, tables, networks, Markdown text, and HTML files). If the component files are in the first-level folders, an `overview` subsection will be created automatically. 
 
 Here is an example layout:
 
 ```
 report_folder/
 ├── section1/
+│   ├── table1.tsv
 │   └── subsection1/
-│       ├── table.csv
+│       ├── table2.csv
 │       ├── image1.png
 │       └── chart.json
 ├── section2/
+│   ├── image2.jpg
 │   ├── subsection1/
 │   │   ├── summary_table.xls
 │   │   └── network_plot.graphml
@@ -136,9 +144,6 @@ report_folder/
 │       └── summary.md
 ```
 
-> [!WARNING]
-> VueGen currently requires each section to contain at least one subsection folder. Defining only sections (with no subsections) or using deeper nesting levels (i.e., sub-subsections) will result in errors. In upcoming releases, we plan to support more flexible directory structures.
-
 The titles for sections, subsections, and components are extracted from the corresponding folder and file names, and afterward, users can add descriptions, captions, and other details to the configuration file. Component types are inferred from the file extensions and names.
 The order of sections, subsections, and components can be defined using numerical suffixes in folder and file names.
 
@@ -174,14 +179,19 @@ docker run --rm \
 
 ## GUI
 
+We have a simple GUI for VueGen that can be run locally or through a standalone executable.
+
 ### Local GUI
 
-We have a simple GUI for VueGen that can be run locally or through a standalone executable.
-For now you will need to have a copy of this repository.
+To use the **local GUI**, you should clone this repository and install the required dependencies. You can do this by running the following command in the root directory of the cloned repository:
 
 ```bash
 pip install '.[gui]'
-cd gui
+```
+
+Then, you should move to the `gui` folder and execute the `app.py` Python file:
+
+```bash
 python app.py
 ```
 
@@ -190,53 +200,66 @@ python app.py
 The **bundle GUI** with the VueGen package is available under the
 [latest releases](https://github.com/Multiomics-Analytics-Group/vuegen/releases/latest).
 You will need to unzip the file and run `vuegen_gui` in the unpacked main folder.
-Most dependencies are included into the bundle using PyInstaller.
+Most dependencies are included into the bundle using [PyInstaller][pyinstaller].
 
-Streamlit works out of the box as a purely Python based package. For `html` creation you will have to
-have a Python 3.12 installation with the `jupyter` package installed as `quarto` needs to start
+Streamlit works out of the box as a purely Python based package. For the rest of report types you 
+will have to have a **Python 3.12** installation with the `jupyter` package installed, as `quarto` needs to start
 a kernel for execution. This is also true if you install `quarto` globally on your machine.
 
-We recommend using miniforge to install Python and the conda package manager:
-
-- [conda-forge.org/download/](https://conda-forge.org/download/)
+> [!TIP]
+> It is advisable to create a virtual environment to manage depenendencies and avoid conflicts with existing packages. 
+You can use the virtual environment manager of your choice, such as `poetry`, `conda`, or `pipenv`. 
+We recommend using [miniforge][conda-download] to install Python and the `conda` package manager.
 
-We continous our example assuming you have installed the `miniforge` distribution for your
-machine (MacOS with arm64/ apple silicon or x86_64/ intel or Windows x86_64). Also download
-the [latest `vuegen_gui` bundle](https://github.com/Multiomics-Analytics-Group/vuegen/releases/latest)
+We assume you have installed the `miniforge` distribution for your machine (MacOS with arm64/ apple silicon 
+or x86_64/ intel or Windows x86_64). Also, download the 
+[latest `vuegen_gui` bundle](https://github.com/Multiomics-Analytics-Group/vuegen/releases/latest)
 from the releases page according to your operating system.
 
+You can create a new conda environment with Python 3.12 and the `jupyter` and `vuegen` package:
+
+```bash
+conda create -n vuegen_gui -c conda-forge python=3.12 jupyter vuegen
+```
+
+Then, activate the environment:
+
 ```bash
-conda create -n vuegen_gui -c conda-forge python=3.12 jupyter
-# in case you have errors, install vuegen addtionally
 conda activate vuegen_gui
-pip install vuegen
-# list all conda environments to find the location of the environment
-conda info -e # find environment location
 ```
 
-Find the vuegen_gui path for your local `user`.
+> [!WARNING]
+> If you have errors with the `vuegen` package, you can install it separately using pip, 
+as explained in the installation section.
+
+Now, you can list all conda environments to find the location of the `vuegen_gui` environment:
+
+```bash
+conda info -e
+```
 
-On **MacOS** you need to add a `bin` to the path:
+On **MacOS**, you need to add a `bin` to the path:
 
 ```bash
 /Users/user/miniforge3/envs/vuegen_gui/bin
 ```
 
-On **Windows** you can use the path as displayed by `conda info -e`:
-
-> Note: On Windows a base installation of miniforge with `jupyter` might work as well as
-> the app can see your entire Path which is not the case on MacOS.
+On **Windows**, you can use the path as displayed by `conda info -e`:
 
 ```bash
 C:\Users\user\miniforge3\envs\vuegen_gui
 ```
 
+> [!NOTE]
+> On Windows a base installation of miniforge with `jupyter` might work because
+the app can see your entire Path, which is not the case on MacOS.
+
 More information regarding the app and builds can be found in the
-[GUI README](https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/gui/README.md).
+[GUI README][gui-readme].
 
 ## Case studies
 
-VueGen’s functionality is demonstrated through two case studies:
+VueGen’s functionality is demonstrated through various case studies:
 
 ### 1. Predefined Directory
 
@@ -376,6 +399,9 @@ We appreciate your feedback! If you have any comments, suggestions, or run into
 [emp]: https://earthmicrobiome.org/
 [emp-config]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/example_config_files/Earth_microbiome_vuegen_demo_notebook_config
 [emp-dir]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/example_data/Earth_microbiome_vuegen_demo_notebook
+[conda-download]: https://conda-forge.org/download/
+[gui-readme]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/gui/README.md
+[pyinstaller]: https://pyinstaller.org/
 [st-cloud]: https://streamlit.io/cloud
 [stlite_repo]: https://github.com/whitphx/stlite
 [st-forum-exe]: https://discuss.streamlit.io/t/streamlit-deployment-as-an-executable-file-exe-for-windows-macos-and-android/6812

docs/images/vuegen_schema_diagram.png

@@ -17,10 +17,7 @@ sections_readme/execution
 sections_readme/gui
 sections_readme/case_studies
 sections_readme/web_app_deploy
-sections_readme/contributing
 sections_readme/citation
-sections_readme/credits
-sections_readme/contact
 ```
 
 ```{toctree}
@@ -44,9 +41,18 @@ vuegen_Chatbot_configfile
 reference/vuegen
 ```
 
+```{toctree} 
+:maxdepth: 1
+:caption: Project Support
+
+sections_readme/contributing
+sections_readme/credits
+sections_readme/contact
+```
+
 ```{toctree}
 :maxdepth: 1
-:caption: MISC:
+:caption: Extra Materials
 :hidden:
 
 README.md

docs/index.md

@@ -63,7 +63,7 @@ Windows and macOS specific options:
 
 ## Quarto notebook execution
 
-- add python exe to bundle as suggested [on stackoverflow](https://stackoverflow.com/a/72639099/9684872) [not this way at least]
+- Add python exe to bundle as suggested [on stackoverflow](https://stackoverflow.com/a/72639099/9684872) [not this way at least]
 
 ## test shipping a python virtual environment with vuegen installed
 
@@ -156,14 +156,14 @@ python -m venv .venv --copies --clear --prompt vuegenvenv
 On windows the default Paths is available in the application. This would allow to use
 the default python installation and a global quarto installation.
 
-to test, one could
+To test, one could
 
-- use global quarto and python installations can be used
-- add a deactivate button into app for bundled quarto (so path is not set)
+- Use global quarto and python installations can be used
+- Add a deactivate button into app for bundled quarto (so path is not set)
 
 ### On MacOs
 
-- on MacOs the default paths are not set, but only the minimal one `/usr/bin:/bin:/usr/sbin:/sbin`,
+- On MacOs the default paths are not set, but only the minimal one `/usr/bin:/bin:/usr/sbin:/sbin`,
   see pyinstaller hints
   [on path manipulations](https://pyinstaller.org/en/stable/common-issues-and-pitfalls.html#macos)
-- requires to add path to python environment manually
+- Requires to add path to python environment manually