Reorganize docs, add changelog

Author: WardBrian

docsrc/_templates/title.html

@@ -1,2 +1,2 @@
 <!-- This will display the version of the docs -->
-<a class='navbar-brand' href='index.html'>CmdStanPy {{ version }}</a>
+<a class='navbar-brand' href='{{ pathto(root_doc) }}'>CmdStanPy {{ version }}</a>

docsrc/changes.rst

@@ -0,0 +1,53 @@
+.. py:currentmodule:: cmdstanpy
+
+.. NOTE FOR MAINTAINERS: This should be updated just before the release action is run, not every PR.
+
+What's New
+==========
+
+For full changes, see the `Releases page <https://github.com/stan-dev/cmdstanpy/releases>`__ on GitHub.
+
+CmdStanPy 1.0.4
+---------------
+
+- Fix an issue with :func:`cmdstanpy.install_cmdstan()` where the installation would report that it had failed even when it had not.
+
+CmdStanPy 1.0.3
+---------------
+
+- Fix an issue where Stan fit objects were not ``pickle``-able when they previously were.
+
+  .. warning::
+      We still do not recommend pickling cmdstanpy objects, but rather using functions :meth:`~CmdStanMCMC.save_csvfiles` and :func:`~cmdstanpy.from_csv`.
+
+CmdStanPy 1.0.2
+---------------
+
+- CmdStanPy can now format (and canonicalize) your Stan files with :meth:`CmdStanModel.format()`
+- Stan variables can now be accessed from fit objects using the `.` syntax when no naming conflicts occur. For example, previous code ``fit.stan_variable("my_cool_variable")`` can now be written ``fit.my_cool_variable``
+- CmdStanPy is more robust to running in threaded environments and tries harder to not overwrite its own output files
+- The ``install_cmdstan`` script can now be run in interactive mode using ``--interactive``/``-i``
+- CmdStanPy now computes some diagnostics after running HMC and will warn you about post-warmup divergences and treedepth exceptions
+- Runtime exceptions in the ``generated quantities`` block should be recognized better now.
+- The default level of precision used by :meth:`CmdStanMCMC.summary()` is now 6, as it is when ``stansummary`` is used from the command line.\
+- Various documentation improvements
+
+
+CmdStanPy 1.0.1
+---------------
+
+- Support new optimizations in CmdStan 2.29
+- Support complex numbers as both inputs and outputs of Stan programs
+- Sped up assembling output by only reading draws at most once
+- Fixed an issue where a command failing could change your working directory
+- Improve error messages in some cases
+- CmdStanPy no longer changes the global root logging level
+
+.. note::
+    The minimum supported version for CmdStanPy is now Python 3.7.
+
+
+CmdStanPy 1.0.0
+---------------
+
+- Initial release

docsrc/conf.py

@@ -133,7 +133,7 @@ def emit(self, record):
 
 # General information about the project.
 project = 'CmdStanPy'
-copyright = '2021, Stan Development Team'
+copyright = '2022, Stan Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -192,7 +192,6 @@ def emit(self, record):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = 'sphinx_rtd_theme'
 html_theme = 'pydata_sphinx_theme'  # https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html
 # theme is customized via _templates/
 
@@ -225,7 +224,7 @@ def emit(self, record):
     "show_toc_level": 2,
 }
 
-html_sidebars = {"**": [], "index": ['logo'], "overview": ['logo']}
+html_sidebars = {"**": [], "index": ['logo'], "users-guide/overview": ['logo']}
 
 html_context = {
     "github_user": "stan-dev",
@@ -426,7 +425,7 @@ def emit(self, record):
         'https://docs.python.org/{.major}'.format(sys.version_info),
         None,
     ),
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
     'xarray': ('https://xarray.pydata.org/en/stable/', None),
 }

docsrc/index.rst

@@ -24,12 +24,11 @@ set of model, data, and posterior estimates.
 .. toctree::
    :maxdepth: 4
 
-   overview
    installation
-   hello_world
-   workflow
-   examples
-   community
+   users-guide
    api
+   changes
+   community
+
 
 :ref:`genindex`

docsrc/users-guide.rst

@@ -0,0 +1,13 @@
+User's Guide
+============
+
+This section provides examples and some narrative description about the
+usage of CmdStanPy.
+
+.. toctree::
+    :titlesonly:
+
+    users-guide/overview
+    users-guide/hello_world
+    users-guide/workflow
+    users-guide/examples