Add internal api doc

Author: WardBrian

cmdstanpy/__init__.py

@@ -50,6 +50,7 @@ def _cleanup_tmpdir() -> None:
 from .utils import set_cmdstan_path  # noqa
 from .utils import (
     cmdstan_path,
+    cmdstan_version,
     install_cmdstan,
     set_make_env,
     show_versions,
@@ -71,4 +72,5 @@ def _cleanup_tmpdir() -> None:
     'write_stan_json',
     'show_versions',
     'rebuild_cmdstan',
+    'cmdstan_version',
 ]

cmdstanpy/install_cxx_toolchain.py

@@ -24,11 +24,7 @@
 from typing import Any, Dict, List
 
 from cmdstanpy import _DOT_CMDSTAN
-from cmdstanpy.utils import (
-    pushd,
-    validate_dir,
-    wrap_url_progress_hook,
-)
+from cmdstanpy.utils import pushd, validate_dir, wrap_url_progress_hook
 
 EXTENSION = '.exe' if platform.system() == 'Windows' else ''
 IS_64BITS = sys.maxsize > 2 ** 32

cmdstanpy/utils.py

@@ -1163,6 +1163,7 @@ def show_versions(output: bool = True) -> str:
 
     try:
         deps_info.append(('cmdstan_folder', cmdstan_path()))
+        deps_info.append(('cmdstan', str(cmdstan_version())))
     # pylint: disable=broad-except
     except Exception:
         deps_info.append(('cmdstan', 'NOT FOUND'))

docsrc/api.rst

@@ -4,6 +4,15 @@
 API Reference
 #############
 
+The following documents the public API of CmdStanPy. It is expected to be stable between versions,
+with backwards compatibility between minor versions and deprecation warnings preceeding breaking changes.
+There is also the `internal API <internal_api.rst>`__, which is makes no such guarantees.
+
+.. toctree::
+   :hidden:
+
+   internal_api.rst
+
 *******
 Classes
 *******
@@ -54,22 +63,15 @@ CmdStanVB
    :members:
 
 
-InferenceMetadata
-=================
-
-.. autoclass:: cmdstanpy.InferenceMetadata
-   :members:
-
-RunSet
-======
-
-.. autoclass:: cmdstanpy.stanfit.RunSet
-   :members:
-
 *********
 Functions
 *********
 
+show_versions
+=============
+
+.. autofunction:: cmdstanpy.show_versions
+
 cmdstan_path
 ============
 
@@ -85,6 +87,11 @@ set_cmdstan_path
 
 .. autofunction:: cmdstanpy.set_cmdstan_path
 
+cmdstan_version
+================
+
+.. autofunction:: cmdstanpy.cmdstan_version
+
 set_make_env
 ============
 

docsrc/conf.py

@@ -13,8 +13,8 @@
 # serve to show the default.
 
 import os
-import sys
 import subprocess
+import sys
 
 # debug info
 print("python exec:", sys.executable)

docsrc/env.yml

@@ -3,7 +3,7 @@ channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - python=3.7
+  - python=3.9
   - ipykernel
   - ipython
   - ipywidgets

docsrc/internal_api.rst

@@ -0,0 +1,56 @@
+.. py:currentmodule:: cmdstanpy
+
+######################
+Internal API Reference
+######################
+
+The following documents the internal API of CmdStanPy. No guarantees are made about backwards compatibility between
+minor versions and refactors are expected. If you find yourself needing something exposed here, please
+`open an issue <https://github.com/stan-dev/cmdstanpy/issues>`__ requesting it be added to the `public API <api.rst>`__.
+
+*******
+Classes
+*******
+
+InferenceMetadata
+=================
+
+.. autoclass:: cmdstanpy.InferenceMetadata
+   :members:
+
+RunSet
+======
+
+.. autoclass:: cmdstanpy.stanfit.RunSet
+   :members:
+
+CompilerOptions
+===============
+
+.. autoclass:: cmdstanpy.compiler_opts.CompilerOptions
+   :members:
+
+CmdStanArgs
+===========
+
+.. autoclass:: cmdstanpy.cmdstan_args.CmdStanArgs
+   :members:
+
+SamplerArgs
+===========
+
+.. autoclass:: cmdstanpy.cmdstan_args.SamplerArgs
+   :members:
+
+OptimizeArgs
+============
+
+.. autoclass:: cmdstanpy.cmdstan_args.OptimizeArgs
+   :members:
+
+VariationalArgs
+===============
+
+.. autoclass:: cmdstanpy.cmdstan_args.VariationalArgs
+   :members:
+

test/test_runset.py

@@ -8,7 +8,6 @@
 from cmdstanpy.stanfit import RunSet
 from cmdstanpy.utils import EXTENSION
 
-
 HERE = os.path.dirname(os.path.abspath(__file__))
 DATAFILES_PATH = os.path.join(HERE, 'data')