Skip to content

Commit 4e1c360

Browse files
committed
πŸ“ Docs: update README to add infor about folder structure, --quartocheks argument, and tynitex installation for pdf reports
1 parent 05d36ee commit 4e1c360

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

β€ŽREADME.mdβ€Ž

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,15 @@ quarto check
8383
> [!TIP]
8484
> If quarto is not installed, you can download the command-line interface from the [Quarto website][quarto-cli] for your operating system.
8585
86+
For PDF reports, you need to have a LaTeX distribution installed. This can be done with quarto using the following command:
87+
88+
```bash
89+
quarto install tinytex
90+
```
91+
92+
> [!TIP]
93+
> Also, you can add the `--quarto_checks` argument to the VueGen command to check and install the required dependencies automatically.
94+
8695
### Docker
8796

8897
If you prefer not to install VueGen on your system, a pre-configured Docker container is available. It includes all dependencies, ensuring a fully reproducible execution environment. See the [Execution section](#execution) for details on running VueGen with Docker. The official Docker images are available at [quay.io/dtu_biosustain_dsp/vuegen][vuegen-docker-quay]. The Dockerfiles to build the images are available [here][docker-folder].
@@ -105,12 +114,41 @@ vuegen --directory docs/example_data/Earth_microbiome_vuegen_demo_notebook --rep
105114
> [!NOTE]
106115
> By default, the `streamlit_autorun` argument is set to False, but you can use it in case you want to automatically run the streamlit app.
107116
117+
### Folder structure
118+
119+
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).
120+
121+
Here is an example layout:
122+
```
123+
report_folder/
124+
β”œβ”€β”€ section1/
125+
β”‚ └── subsection1/
126+
β”‚ β”œβ”€β”€ table.csv
127+
β”‚ β”œβ”€β”€ image1.png
128+
β”‚ └── chart.json
129+
β”œβ”€β”€ section2/
130+
β”‚ β”œβ”€β”€ subsection1/
131+
β”‚ β”‚ β”œβ”€β”€ summary_table.xls
132+
β”‚ β”‚ └── network_plot.graphml
133+
β”‚ └── subsection2/
134+
β”‚ β”œβ”€β”€ report.html
135+
β”‚ └── summary.md
136+
```
137+
138+
> [!WARNING]
139+
> 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.
140+
141+
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.
142+
The order of sections, subsections, and components can be defined using numerical suffixes in folder and file names.
143+
108144
It's also possible to provide a configuration file instead of a directory:
109145

110146
```bash
111147
vuegen --config docs/example_config_files/Earth_microbiome_vuegen_demo_notebook.yaml --report_type streamlit
112148
```
113149

150+
If a configuration file is given, users can specify titles and descriptions for sections and subsections, as well as component paths and required attributes, such as file format and delimiter for dataframes, plot types, and other details.
151+
114152
The current report types supported by VueGen are:
115153

116154
- Streamlit

0 commit comments

Comments
Β (0)