Migration jupyter to marimo notebooks

docs/Makefile

@@ -1,18 +1,36 @@
 # Minimal makefile for Sphinx documentation
+# Preferência: uv (recomendado pelo marimo) > venv > sphinx-build do PATH
 #
 
-# You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = ross
 SOURCEDIR     = .
 BUILDDIR      = _build
+SPHINXPROJ    = ross
+
+# Detectar uv (recomendado pelo marimo: https://docs.marimo.io/guides/package_management/using_uv/)
+UV_AVAILABLE  = $(shell command -v uv 2>/dev/null && echo 1)
+# Fallback: venv do projeto
+VENV_BIN      = $(if $(wildcard ../venv/bin/sphinx-build),../venv/bin/,)
+# Comando de build: uv run usa o ambiente do projeto (deps instaladas com uv pip install -r docs/requirements.txt)
+ifeq ($(UV_AVAILABLE),1)
+  SPHINXBUILD = uv run --project .. sphinx-build
+else
+  SPHINXBUILD = $(VENV_BIN)sphinx-build
+endif
+
+# Com venv (sem uv), marimo no PATH para sphinx-marimo
+export PATH := $(if $(VENV_BIN),$(abspath $(VENV_BIN)):$(PATH),$(PATH))
+
+# Instalar deps da documentação com uv (recomendado pelo marimo) e aplicar patch --show-code
+install-deps:
+	cd .. && uv pip install -e . && uv pip install -r docs/requirements.txt
+	cd .. && uv run python docs/tools/patch_sphinx_marimo_show_code.py
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile install-deps
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/conf.py

@@ -46,6 +46,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx_marimo",
     "myst_nb",
     "sphinxcontrib.bibtex",
     "sphinx_copybutton",
@@ -75,6 +76,13 @@
 #
 source_suffix = [".rst", ".md", ".ipynb"]
 
+# --- Configuração sphinx-marimo ---
+marimo_notebook_dir = "user_guide"
+marimo_default_height = "600px"
+marimo_default_width = "100%"
+marimo_click_to_load = False  # Carrega o notebook ao abrir a página (sem botão)
+marimo_load_button_text = "Carregar Notebook Interativo"
+
 # The master toctree document.
 master_doc = "index"
 
@@ -92,7 +100,12 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "user_guide/*.ipynb",  # Migrados para marimo (.py + .rst)
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "abap"

docs/requirements.txt

@@ -1,5 +1,7 @@
-Sphinx==8.2.3
+Sphinx>=7.4,<8.2
 myst-nb==1.3.0
+marimo
+sphinx-marimo
 sphinxcontrib-bibtex==2.6.5
 sphinx-copybutton==0.5.2
 numpydoc==1.9.0

docs/tools/patch_sphinx_marimo_show_code.py

@@ -0,0 +1,38 @@
+"""
+Aplica patch no sphinx-marimo para usar --show-code no export html-wasm,
+exibindo o código nos notebooks embutidos na documentação.
+
+Execute após: pip install sphinx-marimo
+Uso: python docs/tools/patch_sphinx_marimo_show_code.py
+"""
+import site
+from pathlib import Path
+
+try:
+    import sphinx_marimo
+except ImportError:
+    print("sphinx-marimo não instalado. Execute: pip install sphinx-marimo")
+    raise SystemExit(1)
+
+builder_path = Path(sphinx_marimo.__file__).parent / "builder.py"
+text = builder_path.read_text()
+
+# Formato original (uma linha) do sphinx-marimo
+old_one_line = '["marimo", "export", "html-wasm", str(notebook_path), "-o", str(output_path), "--force"]'
+# Formato com quebra de linha
+old_multiline = '"--force"],'
+new_multiline = '"--force", "--show-code"],'
+already_patched = "--show-code" in text and "html-wasm" in text
+
+if already_patched:
+    print("Patch já aplicado em", builder_path)
+elif old_one_line in text:
+    new_one_line = old_one_line.replace('"--force"]', '"--force", "--show-code"]')
+    builder_path.write_text(text.replace(old_one_line, new_one_line))
+    print("Patch aplicado em", builder_path)
+elif old_multiline in text:
+    builder_path.write_text(text.replace(old_multiline, new_multiline))
+    print("Patch aplicado em", builder_path)
+else:
+    print("Não foi possível encontrar o trecho esperado em", builder_path)
+    raise SystemExit(1)

docs/user_guide/example_1.py

@@ -0,0 +1,157 @@
+import marimo
+
+__generated_with = "0.19.9"
+app = marimo.App()
+
+
+@app.cell
+def _():
+    import marimo as mo
+
+    return (mo,)
+
+
+@app.cell
+async def _():
+    """No navegador (Pyodide), instala plotly via micropip antes dos imports."""
+    import sys
+    if "pyodide" in sys.modules:
+        import micropip
+        await micropip.install("plotly")
+    _packages_ready = True
+    return (_packages_ready,)
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    Example 1 - Number of DOF influence in Natural Frequency
+    =========
+    In this example, we use the rotor seen in Example 5.8.1 from {cite}`friswell2010dynamics`. Which is a symmetric rotor with a single disk in the center. The shaft is hollow with an outside diameter of $80 mm$, an inside
+    diameter of $30 mm$, and a length of $1.2 m$ and it is modeled using Euler-Bernoulli elements, with no internal shaft damping.
+    The bearings are rigid and short and the disk has a diameter of $400 mm$ and a thickness
+    of $80 mm$.
+    The disk and shaft elements are made of steel.
+    """)
+    return
+
+
+@app.cell
+def _(_packages_ready):
+    try:
+        import numpy as np
+        import plotly.graph_objects as go
+        import ross as rs
+        import plotly.io as pio
+        pio.renderers.default = "notebook"
+        _deps_ok = True
+    except ModuleNotFoundError:
+        _deps_ok = False
+        np = go = rs = None
+    return (go, np, rs, _deps_ok)
+
+
+@app.cell
+def _(mo, rs, _deps_ok):
+    if not _deps_ok or rs is None:
+        mo.md(
+            r"""
+            **Notebook no navegador (Pyodide):** A biblioteca **ROSS** não está disponível no browser.
+            (Plotly é instalado automaticamente via micropip.) Para rodar este exemplo com ROSS localmente use **uv** (recomendado):  
+            `uv run marimo edit docs/user_guide/example_1.py`
+            """
+        )
+        steel = None
+    else:
+        steel = rs.materials.steel
+    return (steel,)
+
+
+@app.cell
+def _():
+    number_of_elements = [2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 40, 60]
+    return (number_of_elements,)
+
+
+@app.cell
+def _(rs, steel, _deps_ok):
+    if not _deps_ok or rs is None or steel is None:
+        create_rotor = None
+    else:
+        def create_rotor(n_el):
+            """Create example rotor with given number of elements."""
+            shaft = [
+                rs.ShaftElement(1.2 / (n_el), idl=0.03, odl=0.08, material=steel)
+                for i in range(n_el)
+            ]
+            disks = [
+                rs.DiskElement.from_geometry(
+                    n=(n_el / 2), material=steel, width=0.08, i_d=0.08, o_d=0.4
+                )
+            ]
+            bearings = [
+                rs.BearingElement(0, kxx=1e15, cxx=0),
+                rs.BearingElement(n_el, kxx=1e15, cxx=0),
+            ]
+            return rs.Rotor(shaft, disks, bearings)
+    return (create_rotor,)
+
+
+@app.cell
+def _(create_rotor, go, np, number_of_elements):
+    if create_rotor is None or go is None or np is None:
+        analysis = None
+    else:
+        def analysis(speed):
+            """Perform convergence analysis for a given speed."""
+            n_eigen = 8
+            rotor_80 = create_rotor(80)
+            modal_80 = rotor_80.run_modal(speed, num_modes=2 * n_eigen)
+            errors = np.zeros([len(number_of_elements), n_eigen])
+            for i, n_el in enumerate(number_of_elements):
+                rotor = create_rotor(n_el)
+                modal = rotor.run_modal(speed, num_modes=2 * n_eigen)
+                errors[i, :] = abs(
+                    100 * (modal.wn[:n_eigen] - modal_80.wn[:n_eigen]) / modal_80.wn[:n_eigen]
+                )
+            fig = go.Figure()
+            for i in range(8):
+                fig.add_trace(
+                    go.Scatter(x=number_of_elements, y=errors[:, i], name=f"Mode {i}")
+                )
+            fig.update_layout(
+                xaxis=dict(title="Number of degrees of freedom"),
+                yaxis=dict(type="log", title="Natural Frequency Error(%)"),
+            )
+            return fig
+    return (analysis,)
+
+
+@app.cell
+def _(analysis):
+    if analysis is not None:
+        analysis(speed=0)
+    return
+
+
+@app.cell
+def _(analysis, np):
+    if analysis is not None and np is not None:
+        analysis(speed=5000 * np.pi / 30)
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## References
+
+    ```{bibliography}
+    :filter: docname in docnames
+    ```
+    """)
+    return
+
+
+if __name__ == "__main__":
+    app.run()

docs/user_guide/example_1.rst

@@ -0,0 +1,5 @@
+Example 1
+=========
+
+.. marimo:: example_1.py
+   :height: 700px