docs: documentation overhaul

eurocontrol · Oct 4, 2024 · 005d197 · 005d197
1 parent 19bcd7f
commit 005d197
Show file tree

Hide file tree

Showing 24 changed files with 202 additions and 66 deletions.
diff --git a/docs/source/TCL.rst → docs/source/API_reference/TCL.rst b/docs/source/TCL.rst → docs/source/API_reference/TCL.rst
diff --git a/docs/source/aircraft.rst → docs/source/API_reference/aircraft.rst b/docs/source/aircraft.rst → docs/source/API_reference/aircraft.rst
diff --git a/docs/source/atmosphere.rst → docs/source/API_reference/atmosphere.rst b/docs/source/atmosphere.rst → docs/source/API_reference/atmosphere.rst
diff --git a/docs/source/bada3.rst → docs/source/API_reference/bada3.rst b/docs/source/bada3.rst → docs/source/API_reference/bada3.rst
diff --git a/docs/source/bada4.rst → docs/source/API_reference/bada4.rst b/docs/source/bada4.rst → docs/source/API_reference/bada4.rst
diff --git a/docs/source/badaH.rst → docs/source/API_reference/badaH.rst b/docs/source/badaH.rst → docs/source/API_reference/badaH.rst
diff --git a/docs/source/configuration.rst → docs/source/API_reference/configuration.rst b/docs/source/configuration.rst → docs/source/API_reference/configuration.rst
diff --git a/docs/source/constants.rst → docs/source/API_reference/constants.rst b/docs/source/constants.rst → docs/source/API_reference/constants.rst
diff --git a/docs/source/conversions.rst → docs/source/API_reference/conversions.rst b/docs/source/conversions.rst → docs/source/API_reference/conversions.rst
diff --git a/docs/source/flightTrajectory.rst → ...source/API_reference/flightTrajectory.rst b/docs/source/flightTrajectory.rst → ...source/API_reference/flightTrajectory.rst
diff --git a/docs/source/geodesic.rst → docs/source/API_reference/geodesic.rst b/docs/source/geodesic.rst → docs/source/API_reference/geodesic.rst
diff --git a/docs/source/magnetic.rst → docs/source/API_reference/magnetic.rst b/docs/source/magnetic.rst → docs/source/API_reference/magnetic.rst
diff --git a/docs/source/trajectoryPrediction.rst → ...ce/API_reference/trajectoryPrediction.rst b/docs/source/trajectoryPrediction.rst → ...ce/API_reference/trajectoryPrediction.rst
diff --git a/docs/source/_static/pyBADA_architecture.png b/docs/source/_static/pyBADA_architecture.png
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -0,0 +1,11 @@
+Architecture
+============
+
+.. _architecture_figure:
+
+.. figure:: _static/pyBADA_architecture.png
+   :alt: Image description
+   :width: 80%
+   :align: center
+
+   Figure 1: pyBADA simplified Architecture.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -2,33 +2,39 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../src'))
+
+sys.path.insert(0, os.path.abspath("../../src"))
 
 # -- Project information -----------------------------------------------------
 
-project = 'pybada'
-author = 'EUROCONTROL'
-copyright = "2024, EUROCONTROL"
-release = '0.1.0'
+project = "pybada"
+author = "Your Name"
+release = "0.1"  # Replace with your project's version
 
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.autosummary',
-    'sphinx_rtd_theme'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx_gallery.gen_gallery",
 ]
 
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples",  # Path to your example scripts
+    "gallery_dirs": "auto_examples",  # Path where to save generated output
+    "filename_pattern": "^((?!skip_).)*$",  # Only include scripts not starting with 'skip_'
+}
+
 autosummary_generate = True
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
 # add_module_names = False
-modindex_common_prefix = ['pyBADA.']
+modindex_common_prefix = ["pyBADA."]
 
 # -- Options for HTML output -------------------------------------------------
 
-html_theme = 'sphinx_rtd_theme'
-# html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,50 +1,28 @@
-pyBADA documentation
+Welcome to pyBADA's documentation!
 ==================================
 
-pyBADA provides aircraft performance modelling, trajectory prediction and optimisation, and visualisation with BADA in Python.
-
-To get started:
-
-.. code-block:: bash
-
-    pip install pybada
-
-
-About BADA
-==========
-
 Efficient air traffic operations rely on the capability of air traffic management (ATM) systems to accurately predict aircraft trajectories. Likewise, ATM research and development activities require modelling and simulation tools capable of replicating real-life operations and aircraft performances as perfectly as possible.
 
 To enable modelling and simulation of aircraft trajectories, every aircraft in operation shall have a corresponding Aircraft Performance Model (APM).
 
-This is why `EUROCONTROL <https://www.eurocontrol.int/>`_, in cooperation with aircraft manufacturers and operating airlines, has created and maintains an APM called `BADA <https://www.eurocontrol.int/model/bada>`_ (Base of Aircraft Data).
+This is why EUROCONTROL, in cooperation with aircraft manufacturers and operating airlines, has created and maintains an APM called BADA (Base of Aircraft Data).
 
-Owing to this cooperation, BADA prevails as a unique product provided by EUROCONTROL to the aviation community worldwide
+Owning to this cooperation, BADA prevails as a unique product provided by EUROCONTROL to the aviation community worldwide
 
 BADA APM is based on a kinetic approach to aircraft performance modelling. It is made of two components: the Model specifications, which provide the theoretical fundaments used to calculate aircraft performance parameters, and the Datasets containing the aircraft-specific coefficients necessary to perform calculations. 
 
 
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   TCL
-   aircraft
-   atmosphere
-   bada3
-   bada4
-   badaH
-   configuration
-   constants
-   conversions
-   flightTrajectory
-   geodesic
-   magnetic
-   trajectoryPrediction
+   pyBADA
+   architecture
+   userManual
    history
 
+
 Indices and tables
 ==================
 

diff --git a/docs/source/pyBADA.rst b/docs/source/pyBADA.rst
@@ -0,0 +1,19 @@
+API reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   API_reference/aircraft
+   API_reference/atmosphere
+   API_reference/bada3
+   API_reference/bada4
+   API_reference/badaH
+   API_reference/configuration
+   API_reference/constants
+   API_reference/conversions
+   API_reference/flightTrajectory
+   API_reference/geodesic
+   API_reference/magnetic
+   API_reference/TCL
+   API_reference/trajectoryPrediction
diff --git a/docs/source/userManual.rst b/docs/source/userManual.rst
@@ -0,0 +1,8 @@
+User Manual
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   user_manual/introduction
+   user_manual/examples
diff --git a/docs/source/user_manual/examples.rst b/docs/source/user_manual/examples.rst
@@ -0,0 +1,8 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Examples:
+
+   ../auto_examples/index
diff --git a/docs/source/user_manual/introduction.rst b/docs/source/user_manual/introduction.rst
@@ -0,0 +1,56 @@
+Introduction
+============
+
+Identification
+--------------
+PyBADA is a Python-based implementation of BADA APM for aircraft performance modelling, trajectory prediction and optimisation with BADA, including methods to calculate any of the aircraft’s performance characteristics (lift, drag, thrust, and fuel flow), operational flight envelope, BADA airline procedure model and calculation of PTF and PTD files, as defined by the BADA User Manual. It includes modules to calculate atmospheric properties, unit conversions (including the speed conversion) and basic geodesic calculations.
+
+PyBADA offers a full implementation of BADA3, BADA4 and BADAH. 
+
+The complete implementation then builds on top of BADA performance calculation by providing several trajectory segment calculations for all phases of flight (cruise, climb and descend) including acceleration and deceleration computation.
+
+EUROCONTROL is the owner of pyBADA
+
+Purpose
+-------
+PyBADA library has been created with several use cases in mind:
+
+- Help users starting with BADA and aircraft performance modelling to better understand how such a model can be implemented
+- Lower the workload of users planning to implement BADA in their tools, by reusing an already exiting fully functional library;
+- Minimizing the errors and unnecessary mistakes while implementing BADA performance calculations;
+- Help users who are building their own tools to validate the results against the library implemented and validated by the BADA team at EUROCONTROL;
+- Provide a starting platform for research organisations and universities, to build new and interesting tools utilizing BADA performance modelling, without requiring too much time to be spent on BADA implementation, and rather focusing on the research part.
+
+Glossary of Acronyms
+--------------------
+
+.. list-table:: Glossary of Acronyms
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Acronym
+     - Explanation
+   * - ARPM
+     - Airline Procedure Model
+   * - BADA
+     - Base of Aircraft Data
+   * - BADA3
+     - Base of Aircraft Data Family 3
+   * - BADA4
+     - Base of Aircraft Data Family 4
+   * - BADAH
+     - Base of Aircraft Data Family H
+   * - PTD
+     - Performance Table Data
+   * - PTF
+     - Performance Table File
+   * - pyBADA
+     - Python Implementation of BADA
+   * - SW
+     - Software
+   * - TAS
+     - True Air Speed
+   * - TBP
+     - Turboprop
+   * - TCL
+     - Trajectory Computation Light
diff --git a/examples/GALLERY_HEADER.rst b/examples/GALLERY_HEADER.rst
@@ -0,0 +1,8 @@
+Examples Gallery
+================
+
+Welcome to the pyBADA Examples Gallery!
+
+This gallery showcases example scripts demonstrating the usage of the pyBADA package. The examples cover various functionalities and use cases to help you understand how to implement pyBADA in your projects.
+
+Below you will find a collection of scripts with accompanying explanations and outputs.
diff --git a/examples/example_script.py b/examples/example_script.py
@@ -0,0 +1,23 @@
+"""
+Simple Plot
+===========
+
+This script demonstrates how to create a simple plot using matplotlib.
+
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Generate data
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+
+# Create plot
+plt.plot(x, y)
+plt.title("Sine Wave")
+plt.xlabel("x")
+plt.ylabel("sin(x)")
+
+# Display plot
+plt.show()
diff --git a/examples/geodesic.py b/examples/geodesic.py
@@ -1,9 +1,13 @@
 """
+Geodesic Calculation
+====================
+
 Example of using the geodesic module and comparision 
 between Haversine and Vincenty implementation
+
 """
 
-import folium
+# import folium
 
 from pyBADA import conversions as conv
 from pyBADA import geodesic as geo
@@ -24,13 +28,19 @@
 
 # Haversine formula
 distance_haversine = geo.Haversine.distance(
-    LAT_init=LAT_init, LON_init=LON_init, LAT_final=LAT_final, LON_final=LON_final
+    LAT_init=LAT_init,
+    LON_init=LON_init,
+    LAT_final=LAT_final,
+    LON_final=LON_final,
 )
 print("Haversine distance:", distance_haversine)
 
 # Vincenty formula
 distance_vincenty = geo.Vincenty.distance(
-    LAT_init=LAT_init, LON_init=LON_init, LAT_final=LAT_final, LON_final=LON_final
+    LAT_init=LAT_init,
+    LON_init=LON_init,
+    LAT_final=LAT_final,
+    LON_final=LON_final,
 )
 print("Vincenty distance: ", distance_vincenty)
 print("")
@@ -41,19 +51,28 @@
 
 # Haversine formula
 bearing_haversine = geo.Haversine.bearing(
-    LAT_init=LAT_init, LON_init=LON_init, LAT_final=LAT_final, LON_final=LON_final
+    LAT_init=LAT_init,
+    LON_init=LON_init,
+    LAT_final=LAT_final,
+    LON_final=LON_final,
 )
 print("Haversine initial bearing:", bearing_haversine)
 
 # Vincenty formula for initial bearing
 bearing_vincenty = geo.Vincenty.bearing_initial(
-    LAT_init=LAT_init, LON_init=LON_init, LAT_final=LAT_final, LON_final=LON_final
+    LAT_init=LAT_init,
+    LON_init=LON_init,
+    LAT_final=LAT_final,
+    LON_final=LON_final,
 )
 print("Vincenty initial bearing: ", bearing_vincenty)
 
 # Vincenty formula for final bearing
 bearing_vincenty = geo.Vincenty.bearing_final(
-    LAT_init=LAT_init, LON_init=LON_init, LAT_final=LAT_final, LON_final=LON_final
+    LAT_init=LAT_init,
+    LON_init=LON_init,
+    LAT_final=LAT_final,
+    LON_final=LON_final,
 )
 # print("Vincenty final bearing:   ", bearing_vincenty)
 print("")
@@ -98,7 +117,7 @@
 initPoint = (LAT_init, LON_init)
 
 # create a base map
-myMap = folium.Map(location=initPoint, zoom_start=10)
+# myMap = folium.Map(location=initPoint, zoom_start=10)
 
 # construct the lines
 haversineLine = []
@@ -110,23 +129,23 @@
 vincentyLine.append(destPoint_vincenty)
 
 # draw the lines on the map
-folium.PolyLine(haversineLine, color="red", weight=2).add_to(myMap)
-folium.PolyLine(vincentyLine, color="blue", weight=2).add_to(myMap)
+# folium.PolyLine(haversineLine, color="red", weight=2).add_to(myMap)
+# folium.PolyLine(vincentyLine, color="blue", weight=2).add_to(myMap)
 
 # add markers on the map
-folium.Marker(initPoint).add_to(myMap)
-folium.Marker(
-    destPoint_haversine,
-    popup="<i>Haversine</i>",
-    tooltip="Haversine",
-    icon=folium.Icon(color="red"),
-).add_to(myMap)
-folium.Marker(
-    destPoint_vincenty,
-    popup="<i>Vincenty</i>",
-    tooltip="Vincenty",
-    icon=folium.Icon(color="blue"),
-).add_to(myMap)
+# folium.Marker(initPoint).add_to(myMap)
+# folium.Marker(
+# destPoint_haversine,
+# popup="<i>Haversine</i>",
+# tooltip="Haversine",
+# icon=folium.Icon(color="red"),
+# ).add_to(myMap)
+# folium.Marker(
+# destPoint_vincenty,
+# popup="<i>Vincenty</i>",
+# tooltip="Vincenty",
+# icon=folium.Icon(color="blue"),
+# ).add_to(myMap)
 
 # saving the map in the HTML file. This map then can be viewed in the browser and you can interact with it
-myMap.save("map_geodesic.html")
+# myMap.save("map_geodesic.html")