DOC: New Environment class docs pages

.vscode/settings.json

@@ -36,6 +36,7 @@
         "axhline",
         "axup",
         "axvline",
+        "Barrowman",
         "behaviour",
         "bijective",
         "brentq",
@@ -65,11 +66,13 @@
         "cstride",
         "csys",
         "datapoints",
+        "datetime",
         "ddot",
         "deletechars",
         "dimgrey",
         "discretizes",
         "disp",
+        "Doretto",
         "dtype",
         "ECMWF",
         "edgecolor",
@@ -95,6 +98,7 @@
         "genfromtxt",
         "geopotential",
         "geopotentials",
+        "Geospatial",
         "getdata",
         "getfixturevalue",
         "Giorgio",
@@ -103,14 +107,17 @@
         "Glauert",
         "gmaps",
         "Gomes",
+        "Gonçalvez",
         "grav",
         "hemis",
         "hgtprs",
         "hgtsfc",
         "HIRESW",
+        "HRES",
         "hspace",
         "ICONEU",
         "idxmax",
+        "IGRA",
         "imageio",
         "imread",
         "intc",
@@ -121,7 +128,9 @@
         "isbijective",
         "isin",
         "jsonpickle",
+        "Junqueira",
         "jupyter",
+        "Kaleb",
         "Karman",
         "linalg",
         "linestyle",
@@ -130,14 +139,22 @@
         "LSODA",
         "lvhaack",
         "Mandioca",
+        "Marte",
+        "Masatoshi",
+        "Mateus",
+        "Matheus",
         "mathutils",
         "maxdepth",
         "mbar",
         "meshgrid",
+        "Mesoscale",
+        "Meteo",
+        "Meteomatics",
         "Metrum",
         "mult",
         "Mumma",
         "NASADEM",
+        "NCEP",
         "NDAP",
         "ndarray",
         "NDRT",
@@ -149,7 +166,9 @@
         "NOAA",
         "NOAA's",
         "noaaruc",
+        "noaarucsounding",
         "num2pydate",
+        "numpy",
         "outerboundaryis",
         "planform",
         "polystyle",
@@ -169,17 +188,21 @@
         "rwork",
         "savetxt",
         "savgol",
+        "SBMT",
         "scilimits",
         "searchsorted",
         "seealso",
         "simplekml",
         "SIRGAS",
         "somgl",
         "Somigliana",
+        "sqrd",
         "SRTM",
         "SRTMGL",
+        "Stano",
         "subintervals",
         "ticklabel",
+        "timedelta",
         "timezonefinder",
         "tmpprs",
         "toctree",
@@ -190,6 +213,7 @@
         "udot",
         "ufunc",
         "ugrdprs",
+        "Unidimensional",
         "USGS",
         "uwyo",
         "vectorize",
@@ -198,6 +222,7 @@
         "vmax",
         "vmin",
         "vonkarman",
+        "Wanderley",
         "Weibull",
         "windrose",
         "wireframe",

CHANGELOG.md

@@ -35,6 +35,8 @@ Attention: The newest changes should be on top -->
 
 ### Changed
 
+- 
+- DOC: New Environment class docs pages [#644](https://github.com/RocketPy-Team/RocketPy/pull/644)
 
 ### Fixed
 

docs/user/environment.rst

@@ -3,19 +3,12 @@ Environment with RocketPy
 
 .. toctree::
     :maxdepth: 3
-    :caption: Details
+    :caption: Environment class
 
-    ../notebooks/environment/environment_class_usage.ipynb
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Topography
-
-    ../notebooks/environment/topography_usage.ipynb
+    environment/index.rst
 
 .. toctree::
     :maxdepth: 2
-    :caption: Environment Analysis
+    :caption: Environment Analysis class
 
-    ../notebooks/environment/environment_analysis_class_usage.ipynb
-    ../notebooks/environment/environment_analysis_EuroC_example.ipynb
+    environment_analysis.rst

docs/user/environment/0-setup/datetime.rst

@@ -0,0 +1,107 @@
+Date and time
+=============
+
+The first step in setting up the environment is to specify the date and time of
+the flight that will be simulated.
+
+Basic usage
+-----------
+
+RocketPy requires detailed date and time information, including the year, month,
+day, and hour, to accurately forecast the weather.
+Additionally, a timezone can be specified to localize the time.
+
+.. jupyter-execute::
+
+    from rocketpy import Environment
+
+    env = Environment(
+        date=(2022, 2, 16, 18), # year, month, day, hour 
+        timezone="America/New_York"
+    )
+
+.. tip::
+
+    To view a list of available timezones, use the following code:
+
+    .. code-block:: python
+
+        import pytz
+
+        print(pytz.all_timezones)
+
+.. tip::
+
+    When the timezone is omitted, RocketPy assumes it is given in standard UTC.
+
+.. seealso::
+
+    For more information on timezones, see `pytz <https://pypi.org/project/pytz/>`_.
+
+
+Using ``datetime`` objects
+--------------------------
+
+The ``date`` argument also supports ``datetime`` objects, which are python
+built-in objects that represent a date and time.
+
+
+.. jupyter-execute::
+
+    from datetime import datetime
+    from rocketpy import Environment
+
+    date = datetime(2022, 2, 16, 18)
+    env = Environment(date=date)
+
+Setting tomorrow's date
+-----------------------
+
+In the examples we will cover next, it is quite common to set the launch date to
+tomorrow. This can be done by using the ``datetime`` module to calculate the
+date of tomorrow.
+
+.. jupyter-execute::
+
+    from datetime import date, timedelta
+
+    tomorrow = date.today() + timedelta(days=1)
+
+    date_info = (tomorrow.year, tomorrow.month, tomorrow.day, 9)  # Hour given in UTC time
+
+    print("Tomorrow's date:", date_info)
+
+.. note::
+
+    The code above will set the date to tomorrow at 9:00 UTC time. The hour can \
+    be adjusted as needed.
+
+.. danger::
+
+    The ``datetime`` module in Python contains both the ``date`` and ``timedelta`` \
+    classes, as well as the ``datetime`` class. The ``datetime`` class is \
+    used to create datetime objects. It is common to confuse the ``datetime`` \
+    module (which includes various classes and methods for manipulating dates \
+    and times) with the ``datetime`` class itself (which is used to create \
+    specific datetime objects). \
+    See the `official documentation <https://docs.python.org/3/library/datetime.html>`_ \
+    for more information.
+
+
+Alternatively, you can use the ``datetime`` module to calculate the date of
+tomorrow at the same time as the current time, and then pass it to the
+Environment class.
+
+.. jupyter-execute::
+
+    from datetime import datetime, timedelta
+    from rocketpy import Environment
+
+    tomorrow = datetime.now() + timedelta(days=1)
+
+    env = Environment(date=tomorrow)
+
+.. note::
+
+    The code above will set the environment to tomorrow's date at the same time \
+    as the current time. 

docs/user/environment/0-setup/elevation.rst

@@ -0,0 +1,66 @@
+Elevation
+=========
+
+The elevation of the launch site is particularly important for
+determining the rocket's interaction with the atmosphere and Earth's gravitational field.
+
+Known elevation
+---------------
+
+If the elevation, measured in meters above sea level, is known, it can be used
+to initialize an Environment class instance as follows:
+
+.. jupyter-execute::
+
+    from rocketpy import Environment
+
+    env = Environment(elevation=110)
+
+You can change the elevation at any time by using the following method:
+
+.. jupyter-execute::
+
+    env.set_elevation(120)
+
+Using Open-Elevation API
+------------------------
+
+Fortunately, there are alternatives to find an approximate value of the
+elevation if the latitude and longitude values are known.
+
+One very useful and handy option is to use
+`Open-Elevation <https://open-elevation.com/>`_, a free and open-source
+elevation API.
+It is integrated with RocketPy and can be used as follows.
+
+First, initialize a new Environment:
+
+.. jupyter-execute::
+
+    env = Environment(
+        date=(2019, 2, 10, 18),
+        latitude=-21.960641,
+        longitude=-47.482122
+    )
+
+Then, set the elevation using Open-Elevation:
+
+.. jupyter-execute::
+
+    env.set_elevation("Open-Elevation")
+
+To get information from the Environment, use the following method:
+
+.. jupyter-execute::
+
+    env.prints.launch_site_details()
+
+
+Using Atmospheric Models
+------------------------
+
+One option is to use the elevation data supplied by some atmospheric models.
+Since elevation data is crucial for numerical weather prediction, some weather
+models make elevation data available together with other variables.
+This will be covered in the :ref:`atmospheric_models` section.
+

docs/user/environment/0-setup/index.rst

@@ -0,0 +1,13 @@
+Setting Up the Environment
+==========================
+
+The first step is to set up the environment with the basic information.
+The date, time, location, and elevation are the minimum requirements to start
+setting up the environment.
+
+.. toctree::
+   :maxdepth: 1
+
+   Date and Time <datetime.rst>
+   Location <location.rst>
+   Elevation <elevation.rst>

docs/user/environment/0-setup/location.rst

@@ -0,0 +1,23 @@
+Location
+========
+
+Setting up the location is simple using the :meth:`rocketpy.Environment.set_location` method.
+This method allows you to specify the latitude and longitude of the launch site
+and automatically refreshes the atmospheric conditions if a location-dependent
+model is being used.
+
+.. jupyter-execute::
+
+    from rocketpy import Environment
+
+    env = Environment()
+
+    env.set_location(latitude=32.988528, longitude=-106.975056)
+
+    env.prints.launch_site_details()
+
+
+.. important::
+
+    If you use the :meth:`rocketpy.Environment.set_location` method again, the atmospheric \
+    conditions will be automatically refreshed. You can update the location at any time.