Merge pull request #448 from RocketPy-Team/tst/update-workflows

ENH: workflows update and new docker files

.dockerignore

@@ -0,0 +1,46 @@
+# Python files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+db.sqlite3
+/db.sqlite3
+pip-log.txt
+pip-delete-this-directory.txt
+.pytest_cache/
+
+# Documentation and Tests
+docs/
+.coverage
+readthedocs.yml
+.travis.yml
+Makefile
+
+# Binary and Package files
+*.egg-info/
+*.egg
+dist/
+build/
+
+# VCS
+.git/
+.gitignore
+.gitattributes
+.github/
+
+# IDEs and Editors
+.vscode
+
+# Virtual environments
+.venv
+venv
+ENV/
+env/
+
+# Others
+*.log
+
+# Docker
+Dockerfile
+.dockerignore

.github/workflows/test_pytest.yaml

@@ -5,15 +5,16 @@ on:
     types: [opened, synchronize, reopened, ready_for_review]
     paths:
       - "**.py"
+      - ".github/**"
 
 jobs:
-  fail_if_pull_request_is_draft:
+  fail_if_pr_is_draft:
     if: github.event.pull_request.draft == true
     runs-on: ubuntu-18.04
     steps:
       - name: Fails in order to indicate that pull request needs to be marked as ready to review and unit tests workflow needs to pass.
         run: exit 1
-  run_pytest_and_doctest:
+  pytest_and_doctest:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -23,7 +24,10 @@ jobs:
           - windows-latest
         python-version:
           - 3.8
-          - 3.11
+          - 3.12
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: ${{ matrix.python-version }}
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}
@@ -44,6 +48,17 @@ jobs:
           pip install -r requirements-tests.txt
       - name: Test with pytest
         run: |
-          pytest
+          pytest --cov=rocketpy --cov-report=xml
           cd rocketpy
-          pytest --doctest-modules
+          pytest --doctest-modules --cov=rocketpy --cov-report=xml
+      - name: Upload coverage report to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ./coverage/reports/
+          env_vars: OS,PYTHON
+          fail_ci_if_error: true
+          files: ./coverage.xml, ./rocketpy/coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          verbose: true

Dockerfile

@@ -0,0 +1,30 @@
+# Set base image 
+# python:latest will get the latest version of python, on linux
+# Get a full list of python images here: https://hub.docker.com/_/python/tags
+FROM python:latest
+
+# set the working directory in the container
+WORKDIR /RocketPy
+
+# Ensure pip is updated
+RUN python3 -m pip install --upgrade pip
+
+# Copy the dependencies file to the working directory
+COPY requirements.txt .
+COPY requirements-tests.txt .
+
+# Install dependencies
+# Use a single RUN instruction to minimize the number of layers
+RUN pip install \
+    -r requirements.txt \
+    -r requirements-tests.txt
+
+# copy the content of the local src directory to the working directory
+COPY . .
+
+# command to run on container start
+# print the operational system and the python version
+CMD [ "python3", "-c", "import platform;import sys; print('Python ', sys.version, ' running on ', platform.platform())" ]
+
+# Install the rocketpy package # TODO: check if I can put this in editable mode
+RUN pip install .

README.md

@@ -9,6 +9,7 @@
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/RocketPy-Team/rocketpy/blob/master/docs/notebooks/getting_started_colab.ipynb)
 [![PyPI](https://img.shields.io/pypi/v/rocketpy?color=g)](https://pypi.org/project/rocketpy/)
 [![Documentation Status](https://readthedocs.org/projects/rocketpyalpha/badge/?version=latest)](https://docs.rocketpy.org/en/latest/?badge=latest)
+[![codecov](https://codecov.io/gh/RocketPy-Team/RocketPy/graph/badge.svg?token=Ecc3bsHFeP)](https://codecov.io/gh/RocketPy-Team/RocketPy)
 [![Contributors](https://img.shields.io/github/contributors/RocketPy-Team/rocketpy)](https://github.com/RocketPy-Team/RocketPy/graphs/contributors)
 [![Chat on Discord](https://img.shields.io/discord/765037887016140840?logo=discord)](https://discord.gg/b6xYnNh)
 [![Sponsor RocketPy](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/RocketPy-Team)

docker-compose.yml

@@ -0,0 +1,24 @@
+version: '3.8'
+
+services:
+  python38-linux:
+    image: python:3.8
+    volumes:
+      - .:/app
+    working_dir: /app
+    command: bash -c "pip install . && pip install -r requirements-tests.txt && pytest && cd rocketpy && pytest --doctest-modules"
+    logging:
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  python312-linux:
+    image: python:3.12
+    volumes:
+      - .:/app
+    working_dir: /app
+    command: bash -c "pip install . && pip install -r requirements-tests.txt && pytest && cd rocketpy && pytest --doctest-modules"
+    logging:
+      options:
+        max-size: "10m"
+        max-file: "3"

docs/development/docker.rst

@@ -0,0 +1,174 @@
+RocketPy with docker
+=====================
+
+RocketPy does not provide an official docker image, but you can build one
+yourself using the provided `Dockerfile` and `docker-compose.yml` files.
+
+Benefits
+--------
+
+Docker allows you to run applications in containers. The main benefits of
+using docker are:
+
+1. **Isolation**: run RocketPy in a fresh environment, without
+   worrying about dependencies.
+2. **Portability**: run RocketPy on any operational system that supports
+   docker, including the 3 main operational systems (Windows, Linux and Mac).
+3. **Reproducibility**: ensure that tour code is working regardless of the
+   operational system.
+
+Using docker will be specially important when you are not sure if the code
+additions will still run on different operational systems.
+
+Although we have a set of GitHub actions to test the code on different 
+operational systems every time a pull request is made, it is important to
+submit a PR only after you are sure that the code will run flawlessly,
+otherwise quota limits may be reached on GitHub.
+
+Requirements
+-------------
+
+Before you start, you need to install on your machine: 
+
+1. `Docker <https://docs.docker.com/get-docker/>`__, to build and run the image.
+2. `Docker Compose <https://docs.docker.com/compose/install/>`__, to compose multiple images at once.
+3. Also, make sure you have cloned the RocketPy repository in your machine!
+
+Build the image
+----------------
+
+To build the image, run the following command on your terminal:
+
+.. code-block:: console
+   
+   docker build -t rocketpy-image -f Dockerfile .
+
+
+This will build the image and tag it as `rocketpy-image` (you can apply another
+name of your preference if you want).
+
+An image is a read-only template with instructions for creating a Docker
+container (see `Docker docs <https://docs.docker.com/get-started/overview/#docker-objects>`__).
+
+This process may take a while, since it will create an image that could easily
+be 1.5 GB in size.
+But don't worry, you just need to build the image once.
+
+Run the container
+-----------------
+
+Now that you have the image, you can run it as a container:
+
+.. code-block:: console
+
+   docker run -it --entrypoint /bin/bash rocketpy-image
+
+
+This will run the container and open a bash terminal inside it.
+If you are using VSCode, you can even integrate the running container into your
+IDE, allowing you to code and test directly within the container environment.
+This is particularly useful if you want to maintain your usual development setup
+while ensuring consistency in the execution environment.
+For more details on how to do this, refer to the
+`VSCode docs <https://code.visualstudio.com/docs/remote/containers>`__
+on developing inside a container.
+
+Indeed, vscode offers a full support for docker, read the
+`vscode docs <https://code.visualstudio.com/docs/containers/overview#_installation>`__
+for more details
+
+
+Run the unit tests
+--------------------
+
+You might have noticed that the container is running in an isolated environment
+with no access to your machine's files, but the `Dockerfile` already copied the
+RocketPy repository to the container.
+This means that you can run tests (and simulations!) as if you were running
+RocketPy on your machine.
+
+As simple as that, you can run the unit tests:
+
+.. code-block:: console
+   
+   pytest
+
+
+To access a list of all available execution options, see the
+`pytest docs <https://docs.pytest.org/en/latest/how-to/usage.html>`__.
+
+Compose docker images 
+---------------------
+
+We also made available a `docker-compose.yml` file that allows you to compose
+multiple docker images at once.
+Unfortunately, this file will not allow you to test the code on different 
+operational systems at once, since docker images inherits from the host
+operational system.
+However, it is still useful to run the unit tests on different python versions.
+
+Currently, the `docker-compose.yml` file is configured to run the unit tests
+on python 3.8 and 3.12.
+
+To run the unit tests on both python versions, run the following command
+**on your machine**:
+
+.. code-block:: console
+   
+   docker-compose up
+
+Also, you can check the logs of the containers by running:
+
+.. code-block:: console
+   
+   docker-compose logs
+
+
+This command is especially useful for debugging if any issues occur during the
+build process or when running the containers.
+
+After you're done testing, or if you wish to stop the containers and remove the
+services, use the command:
+
+.. code-block:: console
+   
+   docker-compose down
+
+
+This will stop the running containers and remove the networks, volumes, and
+images created by up.
+
+
+Changing to other operational systems
+-------------------------------------
+
+The default image in the `Dockerfile` is based on a Linux distribution.
+However, you can alter the base image to use different operating systems, though
+the process may require additional steps depending on the OS's compatibility
+with your project setup.
+For instance, certain dependencies or scripts may behave differently or require
+different installation procedures, so use it with caution.
+
+To change the base image, you will need to modify the `FROM` statement in the
+`Dockerfile`.
+For example, to use a Windows-based image, you might change:
+
+.. code-block:: Dockerfile
+   
+   FROM python:latest
+
+
+to
+
+.. code-block:: Dockerfile
+   
+   FROM mcr.microsoft.com/windows/servercore:ltsc2019
+
+
+Please note, the above is just an example, and using a different OS may require
+further adjustments in the `Dockerfile`.
+We recommend you to see the official Python images on the Docker Hub for
+different OS options: `Docker Hub Python Tags <https://hub.docker.com/_/python/tags>`__.
+
+Be aware that switching to a non-Linux image can lead to larger image sizes and
+longer pull times.

docs/development/index.rst

@@ -8,6 +8,7 @@ Contributing to RocketPy
    Running RocketPy as a Developer <rocketpy_as_developer.rst>
    GitHub Workflow for RocketPy Hackathon 2022 <github_hackathon.rst>
    Style Guide <style_guide>
+   RocketPy with Docker <docker.rst>
    Building the Documentation <build_docs.rst>
 
 This section is still a work in progress. Here you will find information on how to contribute to our code base.