Merge pull request #111 from forefireAPI/dev

[docs] improvements for joss

Author: filippi

.github/workflows/increment-version.yml

@@ -2,7 +2,8 @@ name: Increment Version on Dev
 
 on:
   push:
-    # branches: [ dev ] we can add back later if needed
+  # we can add back to branch dev if needed
+    branches: [ dev2 ]
   workflow_dispatch:
 
 jobs:

…/getting_started/running_the_example.rst …urce/getting_started/execution_modes.rstdocs/source/getting_started/running_the_example.rst renamed to docs/source/getting_started/execution_modes.rst docs/source/getting_started/running_the_example.rst renamed to docs/source/getting_started/execution_modes.rst

@@ -1,9 +1,17 @@
-.. _running-the-example:
+.. _execution_modes:
 
-Running an Example
+Execution Modes
 ==================
 
-After successfully installing ForeFire (either :doc:`from source <installation>` or via :doc:`Docker <quickstart>`), you can run the example simulation located in the ``tests/runff/`` directory. This helps verify your installation and introduces you to the basic command execution methods.
+In the :doc:`quickstart` guide, you launched the example simulation using the interactive Web UI. That is just one of several ways to operate the ``forefire`` interpreter.
+
+This page details all three primary execution modes, allowing you to choose the best method for your specific task:
+
+-   **Direct Execution (Batch Mode):** Best for standard, non-interactive runs or for use in automated scripts.
+-   **Interactive Console:** Ideal for experimenting with commands step-by-step or inspecting the simulation state.
+-   **Web Interface:** Excellent for visual feedback and interactive demonstrations.
+
+Below, we demonstrate each method using the same ``real_case.ff`` script.
 
 Simulation Files Used
 ---------------------
@@ -51,7 +59,10 @@ This is the simplest way to run a simulation non-interactively by feeding the en
 
     ../../bin/forefire -i real_case.ff
 
-3.  **Observe:** ForeFire will print status messages to the console as it executes the commands within ``real_case.ff``. It will likely create output files (as specified by ``print``/``save`` commands in the script) in the current directory (``tests/runff``).
+3.  **Observe:** ForeFire will create 2 files:
+
+  - ``to_reload.ff``: a Forefire ascii state file ready to be reincluded or modified to run
+  - ``ForeFire.0.nc``: a burning map matrix in netcdf
 
 2: Interactive Console
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -84,15 +95,15 @@ This method starts the ForeFire interpreter first, allowing you to execute the s
 
   .. code-block:: none
 
-    forefire> include[input=real_case.ff]
+    forefire> include[real_case.ff]
 
 
-4.  **Observe:** The simulation will run similarly to Method 1, executing the commands from ``real_case.ff`` and printing output to the console. Afterwards, you remain in the interactive console (``forefire>`` prompt) and can inspect parameters (e.g., ``getParameter[propagationModel]``), run further steps manually (e.g., ``step[dt=600]``), or exit using ``quit[]``.
+4.  **Observe:** The simulation will run similarly to Method 1, executing the commands from ``real_case.ff``. Afterwards, you remain in the interactive console (``forefire>`` prompt) and can inspect parameters (e.g., ``getParameter[propagationModel]``), run further steps manually (e.g., ``step[dt=600]``), or exit using ``quit[]``.
 
 3: Web Interface
 ~~~~~~~~~~~~~~~~
 
-This method uses the built-in HTTP server to provide a web-based console and map visualization. It executes commands in the same way as the interactive console but through your browser.
+This method, which you may have already used in the :doc:`quickstart` guide, uses the built-in HTTP server to provide a web-based console and map visualization. It executes commands in the same way as the interactive console but through your browser.
 
 1.  **Navigate to the test directory** (if not already there):
 
@@ -120,14 +131,14 @@ This method uses the built-in HTTP server to provide a web-based console and map
 
   Alternatively, to launch the HTTP server directly without entering the interactive console first, you can use the `-l` command-line option. This is convenient if you primarily want to use the web interface.
 
-  .. code-block:: none
+  .. code-block:: bash
 
     forefire -l
 
 4.  **Use the Web Interface:**
 
   - Open your browser to ``http://localhost:8000/`` (or the specified port).
-  - In the command input box in the web UI, type ``include[input=real_case.ff]`` and press Enter or click Send. This executes the script file relative to where the interpreter was started (which we ensured was `tests/runff`).
+  - In the command input box in the web UI, type ``include[real_case.ff]`` and press Enter or click Send. This executes the script file relative to where the interpreter was started (which we ensured was `tests/runff`).
   - Click "Refresh Map" periodically to see the simulation progress visually. You can also type other commands directly into the web console.
 
 Choosing a Method

docs/source/getting_started/introduction.rst

@@ -51,7 +51,7 @@ ForeFire is suitable for a range of applications, including:
 Supported Platforms
 -------------------
 
-ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run o Windows via **WSL** (windows Subsystem for Linux) or **Docker**.
+ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run on Windows via **WSL** (Windows Subsystem for Linux) or **Docker**.
 
 About This Documentation
 ------------------------

docs/source/getting_started/quickstart.rst

@@ -76,7 +76,7 @@ Steps
     :align: center
     :width: 90%
 
-  **This confirms your Docker setup is working!** For other ways to run ForeFire scripts (like directly from the command line), see the :doc:`running_the_example` page.
+  **This confirms your Docker setup is working!**
 
 9.  **Stop the Container:**
 
@@ -85,3 +85,10 @@ Steps
   - In the ForeFire console (either web or terminal inside the container), type `quit`.
   - In the container's bash shell (terminal), type `exit`.
   - The `docker run` command used `--rm`, so the container will be automatically removed upon exit.
+
+.. rubric:: Next Steps
+
+Congratulations! You've successfully run your first ForeFire simulation and have a working environment. Here are some recommended next steps to deepen your understanding:
+
+- **Explore Execution Modes:** Learn about the command-line (batch) and interactive console alternatives to the Web UI by reading the :doc:`execution_modes` guide.
+- **Understand the Script:** To see what was inside the ``real_case.ff`` script you just ran, dive into the :doc:`/user_guide/forefire_script` guide.

docs/source/index.rst

@@ -15,7 +15,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire
    getting_started/introduction
    getting_started/quickstart
    getting_started/installation
-   getting_started/running_the_example
+   getting_started/execution_modes
 
 .. toctree::
    :maxdepth: 1

docs/source/requirements.txt

@@ -1,25 +1,11 @@
-alabaster==1.0.0
-babel==2.17.0
-breathe==4.36.0
-certifi==2025.1.31
-charset-normalizer==3.4.1
-docutils==0.21.2
-idna==3.10
-imagesize==1.4.1
-Jinja2==3.1.6
-MarkupSafe==3.0.2
-packaging==24.2
-Pygments==2.19.1
-requests==2.32.4
-snowballstemmer==2.2.0
-Sphinx==8.1.3
-sphinx-rtd-theme==3.0.2
-sphinxcontrib-applehelp==2.0.0
-sphinxcontrib-devhelp==2.0.0
-sphinxcontrib-htmlhelp==2.1.0
-sphinxcontrib-jquery==4.1
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==2.0.0
-sphinxcontrib-serializinghtml==2.0.0
-tomli==2.2.1
-urllib3==2.3.2
+# Core documentation generator
+sphinx>=8.1,<9.0
+
+# Theme for Read the Docs
+sphinx-rtd-theme>=3.0,<4.0
+
+# Doxygen/C++ integration
+breathe>=4.36,<5.0
+
+# A dependency for the RTD theme
+sphinxcontrib-jquery

docs/source/user_guide/forefire_script.rst

@@ -67,7 +67,7 @@ While the exact commands depend on the simulation, a common workflow within a ``
   .. code-block:: none
 
     # Include parameters from a separate file (optional)
-    # include[input=params.ff]
+    # include[params.ff]
 
     # Set specific parameters directly
     setParameters[propagationModel=Rothermel;perimeterResolution=30;dumpMode=geojson]

src/include/Version.h

@@ -1,3 +1,3 @@
 #pragma once
-const char* ff_version = "v2.1.114";
+const char* ff_version = "v2.1.122";