CI: create a CI for testing docs updates + solve different docs issues (#1045)

* CI: create a CI for testing docs updates

* STY: apply ruff format to docs/conf.py

Wrap the long for-loop tuple in StaticJupyterExecute.run to satisfy the
88-char line length, fixing the `ruff format --check` linter failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Update .github/workflows/docs.yml

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Gui-FernandesBR

.github/workflows/docs.yml

@@ -0,0 +1,103 @@
+name: Documentation
+
+on:
+  # Only PRs targeting master (base branch = master) and pushes to master.
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "rocketpy/**" # docstrings feed the autodoc API reference
+      - "pyproject.toml"
+      - "requirements*"
+      - ".readthedocs.yaml"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "rocketpy/**"
+      - "pyproject.toml"
+      - "requirements*"
+      - ".readthedocs.yaml"
+      - ".github/workflows/docs.yml"
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"] # match the Read the Docs build environment
+    env:
+      MPLBACKEND: Agg
+      # Render jupyter-execute cells as static code blocks instead of running
+      # them. This keeps the check fast and deterministic: no simulations and,
+      # crucially, no live network calls to external weather/data servers (which
+      # make the full build slow and flaky). Read the Docs still executes the
+      # cells to render live outputs; this job only validates the docs structure
+      # (reStructuredText, cross-references, toctrees, autodoc API reference).
+      DOCS_SKIP_EXECUTE: "1"
+    steps:
+      - uses: actions/checkout@main
+
+      - name: Install pandoc (required by nbsphinx)
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@main
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: |
+            docs/requirements.txt
+            requirements.txt
+
+      - name: Install dependencies (mirrors .readthedocs.yaml)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install -r requirements.txt
+          pip install .[all]
+
+      - name: Cache Sphinx doctrees
+        uses: actions/cache@main
+        with:
+          path: docs/_build/doctrees
+          key: sphinx-doctrees-${{ github.ref }}-${{ hashFiles('docs/**', 'rocketpy/**') }}
+          restore-keys: |
+            sphinx-doctrees-${{ github.ref }}-
+            sphinx-doctrees-
+
+      - name: Build docs (warnings-as-errors)
+        working-directory: docs
+        run: |
+          sphinx-build -b html -W --keep-going \
+            -d _build/doctrees \
+            -w _build/sphinx-warnings.txt \
+            . _build/html
+
+      - name: Surface Sphinx warnings as annotations
+        if: always()
+        run: |
+          if [ -s docs/_build/sphinx-warnings.txt ]; then
+            echo "::group::Sphinx warnings"
+            cat docs/_build/sphinx-warnings.txt
+            echo "::endgroup::"
+            while IFS= read -r line; do
+              echo "::warning::${line}"
+            done < docs/_build/sphinx-warnings.txt
+          else
+            echo "No Sphinx warnings 🎉"
+          fi
+
+      - name: Upload built HTML
+        if: always()
+        uses: actions/upload-artifact@main
+        with:
+          name: docs-html
+          path: docs/_build/html
+          if-no-files-found: error

docs/conf.py

@@ -67,6 +67,18 @@
     "allow_errors": True,  # Continue building even if cells raise errors
 }
 
+# When DOCS_SKIP_EXECUTE=1, ``jupyter-execute`` directives are rendered as
+# static (non-executing) code blocks instead of running live code. This makes
+# structural doc builds fast and deterministic (no simulations, no network),
+# which is what the GitHub Actions docs check relies on. Read the Docs leaves
+# this unset, so it still executes the cells and renders their live outputs.
+skip_jupyter_execute = os.environ.get("DOCS_SKIP_EXECUTE") == "1"
+
+# Some notebook cells use IPython shell escapes (e.g. ``!pip install rocketpy``)
+# which the Pygments Python lexer cannot tokenize. These are purely cosmetic
+# syntax-highlighting failures, so don't let them fail a warnings-as-errors build.
+suppress_warnings = ["misc.highlighting_failure"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -150,3 +162,46 @@
 html_file_suffix = ".html"
 
 htmlhelp_basename = "rocketpy"
+
+
+def setup(app):
+    """Sphinx entry point for optional build-time customizations."""
+    if skip_jupyter_execute:
+        from docutils.parsers.rst import directives
+        from sphinx.directives.code import CodeBlock
+
+        class StaticJupyterExecute(CodeBlock):
+            """Render ``jupyter-execute`` as a non-executing Python code block.
+
+            Accepts (and ignores) the ``jupyter-execute`` directive options so
+            existing pages parse unchanged, but produces a plain highlighted
+            code block instead of a live-executed cell.
+            """
+
+            required_arguments = 0
+            optional_arguments = 1
+            option_spec = dict(CodeBlock.option_spec)
+            option_spec.update(
+                {
+                    "hide-code": directives.flag,
+                    "hide-output": directives.flag,
+                    "code-below": directives.flag,
+                    "stderr": directives.flag,
+                    "raises": directives.unchanged,
+                }
+            )
+
+            def run(self):
+                for key in (
+                    "hide-code",
+                    "hide-output",
+                    "code-below",
+                    "stderr",
+                    "raises",
+                ):
+                    self.options.pop(key, None)
+                if not self.arguments:
+                    self.arguments = ["python3"]
+                return super().run()
+
+        app.add_directive("jupyter-execute", StaticJupyterExecute, override=True)

docs/notebooks/getting_started.ipynb

@@ -1571,6 +1571,9 @@
   }
  ],
  "metadata": {
+  "nbsphinx": {
+   "orphan": true
+  },
   "colab": {
    "name": "getting_started.ipynb",
    "provenance": [],

docs/notebooks/getting_started_colab.ipynb

@@ -813,6 +813,9 @@
   }
  ],
  "metadata": {
+  "nbsphinx": {
+   "orphan": true
+  },
   "colab": {
    "name": "getting_started.ipynb",
    "provenance": [],

docs/reference/classes/aero_surfaces/_BaseFin.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 _BaseFin Class
 --------------
 

docs/user/environment/1-atm-models/soundings.rst

@@ -22,7 +22,14 @@ http://weather.uwyo.edu/cgi-bin/sounding?region=samer&TYPE=TEXT%3ALIST&YEAR=2019
 
 Initialize a new Environment instance:
 
-.. jupyter-execute::
+.. note::
+
+    The example below is shown as static code (it is not executed during the
+    documentation build) because it requires a live network request to an
+    external University of Wyoming service. Run it locally to fetch the
+    sounding and see the resulting atmospheric plots.
+
+.. code-block:: python
 
     from rocketpy import Environment
 

docs/user/index.rst

@@ -24,6 +24,7 @@ RocketPy's User Guide
    :caption: Special Case Simulations
 
    Compare Flights Class<compare_flights.rst>
+   Flight Comparator Class <flight_comparator.rst>
    Parachute Triggers (Acceleration-Based) <parachute_triggers.rst>
    Deployable Payload <deployable.rst>
    Air Brakes Example <airbrakes.rst>