1036 friendly docs

docs/src/00-getting-started.md

@@ -0,0 +1,73 @@
+# [Getting Started](@id getting-started)
+
+```@contents
+Pages = ["00-getting-started.md"]
+Depth = 3
+```
+
+Let's get you set up! This will only take a few minutes.
+
+## Installing Julia and an Editor
+
+To use Tulipa, you first need to install the open-source [Julia](https://julialang.org) programming language.
+
+Then consider installing a user-friendly code editor, such as [VSCode](https://code.visualstudio.com). Otherwise you will be working in the terminal/command prompt.
+
+## Installing Tulipa
+
+### Starting Julia
+
+Choose one:
+
+- In VSCode: Press `CTRL`+`Shift`+`P` and then `Enter` to start a Julia REPL.
+- In the terminal: Type `julia` and press `Enter`
+
+### Adding Tulipa and dependencies
+
+In Julia:
+
+- Press `]` to enter package mode, then run:
+
+```julia-pkg
+pkg> add TulipaEnergyModel  # The model builder
+pkg> add TulipaIO           # For data handling
+```
+
+Tulipa relies on [DuckDB](https://duckdb.org/) for data-handling:
+
+```julia-pkg
+pkg> add DuckDB
+```
+
+You will also need a solver (optimizer), for now add the open-source solver [HiGHS](https://highs.dev/):
+
+```julia-pkg
+pkg> add HiGHS
+```
+
+If you want to use a different solver, see [How-To-Use](@ref solver).
+
+- Press `backspace` to return to Julia mode
+
+## Using packages in your project
+
+Now that the packages are installed, you need to activate them in your project. You should always have this line at the top of your code, specifying any packages you want to use.
+
+```julia
+using TulipaEnergyModel, TulipaIO, DuckDB
+```
+
+Just to show that it worked, try accessing the documentation of a package:
+
+- Press `?` to enter help mode, then:
+
+```julia
+# Search the documentation for this function from TulipaEnergyModel
+help?> default_parameters
+```
+
+You should see the documentation for the [default_parameters](@ref) function. If Julia says it does not exist, that means TulipaEnergyModel is not in your environment (you need to activate it with `add` and `using` as described above).
+
+## Next Step
+
+Now that you're all set up, head over to our [Beginner Tutorials](@ref beginner-tutorials) to run your first analyses! 🌷

docs/src/20-tutorials.md → docs/src/10-tutorials.md

@@ -3,38 +3,59 @@
 Here are some tutorials on how to use Tulipa.
 
 ```@contents
-Pages = ["20-tutorials.md"]
+Pages = ["10-tutorials.md"]
 Depth = 3
 ```
 
-## [Basic example](@id basic-example)
+## [Beginner Tutorial #1](@id basic-example)
 
-For our first example, let's use a tiny existing dataset.
+For our first analysis, let's use a tiny existing dataset.
 Inside the code for this package, you can find the folder [`test/inputs/Tiny`](https://github.com/TulipaEnergy/TulipaEnergyModel.jl/tree/main/test/inputs/Tiny), which includes all the files necessary to create a model and solve it.
 
 The files inside the "Tiny" folder define the assets and flows data, their profiles, and their time resolution, as well as define the representative periods and which periods in the full problem formulation they represent.
 
 For more details about these files, see [Input](@ref input).
 
-### Run scenario
+### Starting Julia
 
-To read all data from the Tiny folder, perform all necessary steps to create a model, and solve the model, run the following in a Julia terminal:
+Choose one:
 
-```@example
+- In VSCode: Press `CTRL`+`Shift`+`P` and then `Enter` to start a Julia REPL.
+- In the terminal: Type `julia` and press `Enter`
+
+### Run a tiny scenario
+
+In Julia:
+
+```julia @example bt-1
 using DuckDB, TulipaIO, TulipaEnergyModel
 
-input_dir = "../../test/inputs/Tiny" # hide
-# input_dir should be the path to Tiny as a string (something like "test/inputs/Tiny")
-# TulipaEnergyModel.schema_per_table_name contains the schema with columns and types the file must have
+# Set the input directory to the Tiny folder
+input_dir = "../../test/inputs/Tiny" # Something like "test/inputs/Tiny" or "test\\inputs\\Tiny"
+readdir(input_dir) # Check the input directory is correct - this should show the names of the files in the folder
+
+# Create a DuckDB database connection
 connection = DBInterface.connect(DuckDB.DB)
+
+# Read the files into DuckDB tables - luckily the files are already formatted to fit the Model Schema
 read_csv_folder(connection, input_dir; schemas = TulipaEnergyModel.schema_per_table_name)
+
+# Run the scenario and save the result to the energy_problem
 energy_problem = run_scenario(connection)
 ```
 
-The `energy_problem` variable is of type `EnergyProblem`.
-For more details, see the [documentation for that type](@ref TulipaEnergyModel.EnergyProblem) or the section [Structures](@ref structures).
+Congratulations - you just solved your first scenario! 🌷
+
+Now let's look at some of the results:
+
+```julia @example bt-1
+# Check
+
+# Export the results to CSV
+
+```
 
-That's all it takes to run a scenario! To learn about the data required to run your own scenario, see the [Input section](@ref input) of [How to Use](@ref how-to-use).
+## [Beginner Tutorial #2](@id bt-2)
 
 ### Manually running each step
 
@@ -109,7 +130,7 @@ To change this, we can give the functions `run_scenario` or `solve_model!` a
 different optimizer.
 
 !!! warning
-    HiGHS is the only open source solver that we recommend. GLPK and Cbc are not (fully) tested for Tulipa.
+HiGHS is the only open source solver that we recommend. GLPK and Cbc are not (fully) tested for Tulipa.
 
 For instance, let's run the Tiny example using the [GLPK](https://github.com/jump-dev/GLPK.jl) optimizer:
 
@@ -132,7 +153,7 @@ solution = solve_model!(energy_problem, GLPK.Optimizer)
 ```
 
 !!! info
-    Notice that, in any of these cases, we need to explicitly add the GLPK package ourselves and add `using GLPK` before using `GLPK.Optimizer`.
+Notice that, in any of these cases, we need to explicitly add the GLPK package ourselves and add `using GLPK` before using `GLPK.Optimizer`.
 
 In any of these cases, default parameters for the `GLPK` optimizer are used,
 which you can query using [`default_parameters`](@ref).