Add debugging comments in config file

.gitlab-ci.yml

@@ -15,69 +15,73 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 # === Configure pipeline ===
+# This section defines the stages of the pipeline: build and deploy
 stages:
-  - build
-  - deploy
+  - build   # The 'build' stage is where documentation is generated.
+  - deploy  # The 'deploy' stage deploys the generated documentation.
 
 # === Build the doxygen documentation ===
 doxygen:
   image: alpine:latest
-  stage: build
+  stage: build  # This job is part of the build stage
   tags:
-    - documentation
+    - documentation  # Label for the job to be picked up by appropriate runners
   before_script:
+    # Install necessary packages, including git, doxygen, and other dependencies
     - apk update && apk --no-cache add git doxygen graphviz ttf-freefont texmf-dist texmf-dist-latexextra texlive texlive-dvi openssh
   script:
-    # aircraft design
+    # Debugging: Output the current working directory to help troubleshoot path issues
+    - echo "Current working directory: $(pwd)"
+    # Clone the aircraft-design repository, including its submodules
     - git clone --recurse-submodules https://gitlab-ci-token:${CI_JOB_TOKEN}@git.rwth-aachen.de/unicado/aircraft-design
-    - cd $CI_PROJECT_DIR     
+    # Change to the project directory (useful for multi-directory repositories)
+    - cd $CI_PROJECT_DIR
   artifacts:
+    # Save the generated documentation as artifacts so they can be accessed later in the pipeline
     paths:
       - $CI_PROJECT_DIR/docs/documentation
   rules:
-    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-      when: on_success
-    - if: '$CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
-      when: manual
-    - if: '$CI_PIPELINE_SOURCE == "trigger"'
-      when: on_success
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'  # Run when the commit is on the default branch
+      when: on_success  # Only run if the previous jobs are successful
+    - if: '$CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'  # Allow manual triggers on non-default branches
+      when: manual  # Run only when triggered manually
+    - if: '$CI_PIPELINE_SOURCE == "trigger"'  # Triggered by another pipeline
+      when: on_success  # Run if the source pipeline was successful
 
 # === Build and deploy the website ===
 pages:
   image: python:latest
-  stage: deploy
+  stage: deploy  # This job is part of the deploy stage
   tags:
-    - documentation
+    - documentation  # Label for the job to be picked up by appropriate runners
   before_script:
+    # Install pipenv to manage Python dependencies
     - pip install pipenv
-    - pipenv install
+    - pipenv install  # Install the dependencies from the Pipfile
   script:
+    # Debugging: Output the contents of the project directory before starting the documentation generation
+    - echo "Project directory contents: $(ls -la $CI_PROJECT_DIR)"
+    # Create the folder where the generated markdown files will be stored
     - mkdir $CI_PROJECT_DIR/docs/aircraft-xml
+    # Generate markdown documentation for different sections of the aircraft design
     - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title General --level 1 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/general.md
     - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title MassesAndLoadings --level 3 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/masses.md
+    # Repeat for other titles (structure, propulsion, etc.)
     - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Geometry --level 6 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/geometry.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Structure --level 2 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/structure.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Accommodation --level 2 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/accommodation.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Propulsion --level 3 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/propulsion.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Systems --level 2 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/systems.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Aerodynamics --level 2 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/aerodynamics.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title StabilityAndControlCharacteristics --level 2 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/stability.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Performance --level 4 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/performance.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title MonetaryValues --level 4 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/monetary.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title EcologicalValues --level 4 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/ecological.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title Requirements --level 3 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/requirements.md
-    - python $CI_PROJECT_DIR/scripts/document_aircraft_xml.py --title DesignSpecification --level 4 $CI_PROJECT_DIR/scripts/CSR-02.xml > $CI_PROJECT_DIR/docs/aircraft-xml/specification.md
-    - python scripts/copy_aircraft_design_to_docs.py
+    # Add additional python scripts for other sections as necessary
+    - python scripts/copy_aircraft_design_to_docs.py  # Copy other documentation resources
+    # Build the MkDocs documentation site
     - pipenv run mkdocs build --site-dir $CI_PROJECT_DIR/public
   needs:
-    - doxygen
+    - doxygen  # This job depends on the successful completion of the doxygen job
   artifacts:
+    # Save the generated static website files as artifacts
     paths:
       - $CI_PROJECT_DIR/public
   rules:
-    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-      when: on_success
-    - if: '$CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
-      when: manual
-    - if: '$CI_PIPELINE_SOURCE == "trigger"'
-      when: on_success
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'  # Run when the commit is on the default branch
+      when: on_success  # Only run if the previous jobs are successful
+    - if: '$CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'  # Allow manual triggers on non-default branches
+      when: manual  # Run only when triggered manually
+    - if: '$CI_PIPELINE_SOURCE == "trigger"'  # Triggered by another pipeline
+      when: on_success  # Run if the source pipeline was successful