Add Documenter docu

.github/workflows/CI.yml

@@ -62,4 +62,26 @@ jobs:
         with:
           files: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
-
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - name: Install matplotlib
+        run: if [ "$RUNNER_OS" = "Linux" ]; then sudo apt-get install -y python3-matplotlib; fi
+        shell: bash
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using VortexStepMethod
+            DocMeta.setdocmeta!(VortexStepMethod, :DocTestSetup, :(using VortexStepMethod); recursive=true)
+            doctest(VortexStepMethod)'
+

.gitignore

@@ -2,3 +2,4 @@ Manifest.toml
 .vscode/settings.json
 venv
 results/TUDELFT_V3_LEI_KITE/polars/tutorial_testing_stall_model_n_panels_54_distribution_split_provided.pdf
+docs/build/

Project.toml

@@ -16,7 +16,6 @@ Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 BenchmarkTools = "1"
@@ -29,3 +28,10 @@ Measures = "0.3"
 NonlinearSolve = "4"
 StaticArrays = "1"
 Statistics = "1"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[targets]
+test = ["Test", "Documenter"]

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+VortexStepMethod = "ed3cd733-9f0f-46a9-93e0-89b8d4998dd9"

docs/make.jl

@@ -0,0 +1,27 @@
+using VortexStepMethod
+using Pkg
+if ("TestEnv" ∈ keys(Pkg.project().dependencies))
+    if ! ("Documents" ∈ keys(Pkg.project().dependencies))
+        using TestEnv; TestEnv.activate()
+    end
+end
+using Documenter
+
+DocMeta.setdocmeta!(VortexStepMethod, :DocTestSetup, :(using VortexStepMethod); recursive=true)
+
+makedocs(;
+    modules=[VortexStepMethod],
+    authors="Uwe Fechner <[email protected]>, Bart van de Lint <[email protected]> and contributors",
+    sitename="VortexStepMethod.jl",
+    checkdocs=:none,
+    format = Documenter.HTML(prettyurls = haskey(ENV, "CI")),
+    pages=[
+        "Home" => "index.md",
+        "Exported Functions" => "functions.md",
+    ],
+)
+
+deploydocs(;
+    repo="github.com/Albatross-Kite-Transport/VortexStepMethod.jl",
+    devbranch="main",
+)

docs/src/functions.md

@@ -0,0 +1,20 @@
+```@meta
+CurrentModule = VortexStepMethod
+```
+## Main Plotting Functions
+```@docs
+plot_geometry
+plot_distribution
+plot_polars
+```
+
+## Helper Functions
+```@docs
+set_plot_style
+save_plot
+show_plot
+plot_line_segment!
+set_axes_equal!
+create_geometry_plot
+generate_polar_data
+```

docs/src/index.md

@@ -0,0 +1,136 @@
+```@meta
+CurrentModule = VortexStepMethod
+```
+
+# Simulation of a 3D airfoil using the Vortex Step Method
+
+The Vortex Step Method (VSM) is an enhanced lifting line method that improves upon the classic approach by solving the circulation system at the three-quarter chord position, among the most important details. This adjustment allows for more accurate calculations of lift and drag forces, particularly addressing the shortcomings in induced drag prediction. 
+VSM is further refined by coupling it with 2D viscous airfoil polars, making it well-suited for complex geometries, 
+including low aspect ratio wings, as well as configurations with sweep, dihedral, and anhedral angles.
+
+The software presented here includes a couple of examples: a rectangular wing, a leading-edge inflatable kite and a ram-air kite.
+
+This package was translated from the Python code version 1.0.0 available at https://github.com/ocayon/Vortex-Step-Method with some extensions as documented in [News.md](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/NEWS.md).
+
+## Installation
+Install [Julia 1.10](https://ufechner7.github.io/2024/08/09/installing-julia-with-juliaup.html) or later, 
+if you haven't already. On Linux, make sure that Python3, Matplotlib and LaTeX are installed:
+```
+sudo apt install python3-matplotlib
+sudo apt install texlive-full texlive-fonts-extra cm-super
+```
+
+Before installing this software it is suggested to create a new project, for example like this:
+```bash
+mkdir test
+cd test
+julia --project=.
+```
+Then add VortexStepMethod from  Julia's package manager, by typing:
+```julia
+using Pkg
+pkg"add https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl"
+``` 
+at the Julia prompt. You can run the unit tests with the command:
+```julia
+pkg"test VortexStepMethod"
+```
+
+## Running the examples
+If you have git installed, check out this repo because it makes it easier to understand the code:
+```bash
+mkdir repos
+cd repos
+git clone https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl
+cd VortexStepMethod.jl
+```
+You can launch Julia with:
+```bash
+julia --project
+```
+or with:
+```bash
+./bin/run_julia
+```
+In Julia, first update the packages:
+```julia
+using Pkg
+Pkg.update()
+```
+and then you can execute the first example:
+```julia
+include("examples/rectangular_wing.jl")
+```
+To browse the code, it is suggested to use [VSCode](https://code.visualstudio.com/) with the Julia plugin.
+
+## Input
+Three kinds of input data is needed:
+
+- The wing geometry, defined by section:
+  - rec wing two section, two point + polars
+  - kite: model of polars included, n sections to define
+
+- The airflow:
+  - v_app vector
+
+- The configuration:
+  - how many panels  
+    --> two sections make a panel.
+
+Apart from the wing geometry there is no input file yet, the input has to be defined in the code.
+
+### Example for defining the required input:
+```julia
+
+# Step 1: Define wing parameters
+n_panels = 20          # Number of panels
+span = 20.0            # Wing span [m]
+chord = 1.0            # Chord length [m]
+v_a = 20.0            # Magnitude of inflow velocity [m/s]
+density = 1.225        # Air density [kg/m³]
+alpha_deg = 30.0       # Angle of attack [degrees]
+alpha = deg2rad(alpha_deg)
+
+# Step 2: Create wing geometry with linear panel distribution
+wing = Wing(n_panels, spanwise_panel_distribution="linear")
+
+# Add wing sections - defining only tip sections with inviscid airfoil model
+add_section!(wing, 
+    [0.0, span/2, 0.0],    # Left tip LE 
+    [chord, span/2, 0.0],  # Left tip TE
+    "inviscid")
+add_section!(wing, 
+    [0.0, -span/2, 0.0],   # Right tip LE
+    [chord, -span/2, 0.0], # Right tip TE
+    "inviscid")
+
+# Step 3: Initialize aerodynamics
+wa = WingAerodynamics([wing])
+
+# Set inflow conditions
+vel_app = [cos(alpha), 0.0, sin(alpha)] .* v_a
+set_va!(wa, (vel_app, 0.0))  # Second parameter is yaw rate
+```
+It is possible to import the wing geometry using an `.obj` file as shown in the example `ram_air_kite.jl`.
+
+Surfplan files can be converted to an input for `VortexStepMethod.jl` using the [SurfplanAdapter](https://github.com/jellepoland/SurfplanAdapter).
+
+## Output
+- CL, CD, CS (side force coefficient)
+- the spanwise distribution of forces  
+  --> moment coefficients (will be implemented in release 1.1) 
+
+## Citation
+If you use this project in your research, please consider citing it. 
+Citation details can be found in the [CITATION.cff](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/CITATION.cff) file included in this repository.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/LICENSE) file for details.
+
+### Copyright
+Copyright (c) 2022 Oriol Cayon
+
+Copyright (c) 2024 Oriol Cayon, Jelle Poland, TU Delft
+
+Copyright (c) 2025 Oriol Cayon, Jelle Poland, Bart van de Lint
+

src/plotting.jl

@@ -5,7 +5,7 @@
 Set the default style for plots using LaTeX.
 
 # Arguments:
-- `titel_size: size of the plot title in points (default: 16)
+- `titel_size`: size of the plot title in points (default: 16)
 """
 function set_plot_style(titel_size=16)
     rcParams = plt.PyDict(plt.matplotlib."rcParams")
@@ -112,12 +112,15 @@
 end
 
 """
-    set_axes_equal!(ax)
+    set_axes_equal!(ax; zoom=1.8)
 
 Set 3D plot axes to equal scale.
 
 # Arguments
 - ax: 3D plot axis
+
+# Keyword arguments
+zoom: zoom factor (default: 1.8)
 """
 function set_axes_equal!(ax; zoom=1.8)
     x_lims = ax.get_xlim3d() ./ zoom
@@ -153,7 +156,8 @@
 # Keyword arguments
 - zoom: zoom factor (default: 1.8)
 """
-function create_geometry_plot(wing_aero::WingAerodynamics, title, view_elevation, view_azimuth; zoom=1.8)
+function create_geometry_plot(wing_aero::WingAerodynamics, title, view_elevation, view_azimuth; 
+                              zoom=1.8)
     set_plot_style(28)
 
     panels = wing_aero.panels
@@ -245,16 +249,16 @@
 Plot wing geometry from different viewpoints and optionally save/show plots.
 
 # Arguments:
-- wing_aero: struct of type WingAerodynamics
+- `wing_aero`: struct of type WingAerodynamics
 - title: plot title
 
 # Keyword arguments:
-- data_type: string with the file type postfix (default: ".pdf")
-- save_path: path for saving the graphic (default: `nothing``)- is_save
-- is_save: boolean value, indicates if the graphic shall be saved (default: `false`)
-- is_show: boolean value, indicates if the graphic shall be displayed (default: `false`)
-- view_elevation: initial view elevation angle (default: 15) [°]
-- view_azimuth: initial view azimuth angle (default: -120) [°]
+- `data_type``: string with the file type postfix (default: ".pdf")
+- `save_path`: path for saving the graphic (default: `nothing`)
+- `is_save`: boolean value, indicates if the graphic shall be saved (default: `false`)
+- `is_show`: boolean value, indicates if the graphic shall be displayed (default: `false`)
+- `view_elevation`: initial view elevation angle (default: 15) [°]
+- `view_azimuth`: initial view azimuth angle (default: -120) [°]
 
 """
 function plot_geometry(wing_aero::WingAerodynamics, title;
@@ -565,10 +569,10 @@
 
 """
     plot_polars(solver_list, wing_aero_list, label_list;
-    literature_path_list=String[], angle_range=range(0, 20, 2), angle_type="angle_of_attack", angle_of_attack=0.0,
-    side_slip=0.0, v_a=10.0, title="polar", data_type=".pdf", save_path=nothing, 
-    is_save=true,
-    is_show=true)
+    literature_path_list=String[], angle_range=range(0, 20, 2), angle_type="angle_of_attack", 
+    angle_of_attack=0.0, side_slip=0.0, v_a=10.0, 
+    title="polar", data_type=".pdf", save_path=nothing, 
+    is_save=true, is_show=true)
 
 Plot polar data comparing different solvers and configurations.