Add cross-platform docs build helper

README.md

@@ -117,3 +117,19 @@ Use ``dashboard="live"`` to watch the simulation progress in real time, or ``das
 If you run into an issue, please file a new [issue](https://github.com/Project-SimPM/SimPM/issues) for us to discuss. If possible, follow up with a pull request.
 
 If you would like to add a feature, please reach out via [issue](https://github.com/Project-SimPM/SimPM/issues). A feature is most likely to be added if you build it!
+
+## Building the documentation locally
+The documentation is built with Sphinx. Install the doc requirements and the project itself in editable mode so autodoc can import SimPM:
+
+```
+pip install -r docs/requirements.txt
+pip install -e .
+```
+
+Then generate the HTML output:
+
+- Linux/macOS: `make -C docs html` or `python -m sphinx -b html docs/source docs/_build/html`
+- Windows (Command Prompt, without `make`): `docs\make.bat html` or `set PYTHONPATH=src && python -m sphinx -b html docs/source docs/_build/html`
+- Windows (PowerShell, without `make`): `./docs/make.bat html` or `$env:PYTHONPATH="src"; python -m sphinx -b html docs/source docs/_build/html`
+
+Open `docs/_build/html/index.html` in your browser to preview the rendered site.

docs/source/api.rst

@@ -8,4 +8,4 @@ API
    simpm.dashboard
    simpm.des
    simpm.dist
-   simpm.log_cfg
+   simpm.log_cfg

docs/source/api_reference/simpm.dashboard.rst

@@ -1,6 +1,6 @@
-=================
-simpm.dashboard
-=================
+==================================================
+``simpm.dashboard`` --- Dashboard helper components
+==================================================
 
 ``simpm.dashboard`` provides Plotly Dash dashboards for SimPM runs. Use
 ``simpm.run(..., dashboard="post"|"live"|"none")`` to launch a post-run or

docs/source/api_reference/simpm.rst

@@ -1,10 +1,10 @@
-=========
+===================================================
 ``simpm`` --- Simulation Tool in Project Management
-=========
+===================================================
 
 .. autosummary::
    :toctree: generated
 
    simpm.des
    simpm.dist
-   simpm.log_cfg
+   simpm.log_cfg

docs/source/conf.py

@@ -66,11 +66,11 @@
 # a list of builtin themes.
 html_theme = 'sphinx_rtd_theme'
 
-html_static_path = ["_static"]
+html_static_path = ["_static", "images"]
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "_static/simpm_logo.png"
+html_logo = "images/simpm_logo.png"
 
 html_theme_options = {
     "logo_only": True,

tools/build_docs.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS_SOURCE = ROOT / "docs" / "source"
+HTML_BUILD_DIR = ROOT / "docs" / "_build" / "html"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build project documentation without relying on platform-specific tools."
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Remove the existing HTML build directory before rebuilding.",
+    )
+    return parser.parse_args()
+
+
+def clean_build_dir() -> None:
+    if HTML_BUILD_DIR.exists():
+        shutil.rmtree(HTML_BUILD_DIR)
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.clean:
+        clean_build_dir()
+
+    sys.path.insert(0, str(ROOT / "src"))
+    os.environ.setdefault("PYTHONPATH", str(ROOT / "src"))
+
+    from sphinx.cmd import build
+
+    return build.main([
+        "-b",
+        "html",
+        str(DOCS_SOURCE),
+        str(HTML_BUILD_DIR),
+    ])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())