From 3027f1f4d1616836d42762179a0b21265da6878d Mon Sep 17 00:00:00 2001 From: Soujas K Date: Mon, 16 Nov 2026 22:29:11 +0530 Subject: [PATCH] Document include-paths for format_stan_file Signed-off-by: Soujas K --- cmdstanpy/compilation.py | 21 +++++++++++++++++++++ test/test_compilation.py | 23 +++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/cmdstanpy/compilation.py b/cmdstanpy/compilation.py index b02697b3..68471392 100644 --- a/cmdstanpy/compilation.py +++ b/cmdstanpy/compilation.py @@ -446,6 +446,27 @@ def format_stan_file( writing to the file. Only disable this if you're sure you have other copies of the file or are using a version control system like Git. :param stanc_options: Additional options to pass to the stanc compiler. + If the Stan program uses ``#include`` statements, the directories + that contain the included files must be passed as ``include-paths``, + otherwise formatting fails. + + For example, to format a program whose included files are in the + directory ``stan``: + + .. code-block:: python + + from pathlib import Path + from cmdstanpy import format_stan_file + + format_stan_file( + "model.stan", + stanc_options={"include-paths": [Path("stan").resolve()]}, + ) + + The ``#include`` statements are kept in the formatted output. To replace + them with the contents of the included files, also pass + ``canonicalize="includes"``. Note that ``canonicalize`` must be given as + an argument of this function, not inside ``stanc_options``. """ stan_file = Path(stan_file).resolve() diff --git a/test/test_compilation.py b/test/test_compilation.py index addaea55..67709576 100644 --- a/test/test_compilation.py +++ b/test/test_compilation.py @@ -232,6 +232,29 @@ def test_model_format_options() -> None: assert formatted.count('(') == 1 +def test_model_format_includes() -> None: + stan = os.path.join(DATAFILES_PATH, 'bernoulli_include.stan') + + sys_stdout = io.StringIO() + with contextlib.redirect_stdout(sys_stdout): + format_stan_file( + stan, stanc_options={'include-paths': [DATAFILES_PATH]} + ) + formatted = sys_stdout.getvalue() + assert '#include divide_real_by_two.stan' in formatted + + sys_stdout = io.StringIO() + with contextlib.redirect_stdout(sys_stdout): + format_stan_file( + stan, + canonicalize='includes', + stanc_options={'include-paths': [DATAFILES_PATH]}, + ) + formatted = sys_stdout.getvalue() + assert '#include' not in formatted + assert 'real divide_real_by_two(real x)' in formatted + + def test_compilation_options_resolution() -> None: out = resolve_cpp_options(None, multithreading=False) assert not out