diff --git a/README.md b/README.md index 3ff94b7..fcbb528 100644 --- a/README.md +++ b/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. diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/api.rst b/docs/source/api.rst index 1467a6f..acae9b2 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -8,4 +8,4 @@ API simpm.dashboard simpm.des simpm.dist - simpm.log_cfg \ No newline at end of file + simpm.log_cfg diff --git a/docs/source/api_reference/simpm.dashboard.rst b/docs/source/api_reference/simpm.dashboard.rst index b9da78b..8c69393 100644 --- a/docs/source/api_reference/simpm.dashboard.rst +++ b/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 diff --git a/docs/source/api_reference/simpm.rst b/docs/source/api_reference/simpm.rst index 98c4cff..1295e20 100644 --- a/docs/source/api_reference/simpm.rst +++ b/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 \ No newline at end of file + simpm.log_cfg diff --git a/docs/source/conf.py b/docs/source/conf.py index b52105f..04d0fe2 100644 --- a/docs/source/conf.py +++ b/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, diff --git a/tools/build_docs.py b/tools/build_docs.py new file mode 100644 index 0000000..bb96262 --- /dev/null +++ b/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())