Debug doc building [makedocs]

Author: josiekre

HOW_TO_RELEASE.md

@@ -101,7 +101,7 @@
 
     The process of creating and tagging a release will automatically
     trigger various GitHub Actions scripts to build, test, and publish the
-    new release to PyPI and conda forge, assuming there are no errors.
+    new release to PyPI, assuming there are no errors.
 
 10. Build the ActivitySim Standalone Windows Installer.  This is done using 
     GitHub Actions, but it is not done automatically when a release is created, 

README.md

@@ -15,7 +15,7 @@ and benefit from contributions of other agency partners.
 
 :fire: The `main` branch of this repository contains the Consortium's latest
 in-development codebase.  It is not necessarily what you'll get if you install released
-code from conda-forge or by downloading one of the "release" versions here on GitHub,
+code from PyPI or by downloading one of the "release" versions here on GitHub,
 but it is generally expected that code in the `main` branch should be usable.
 
 ## Helpful Links

docs/Makefile

@@ -7,11 +7,6 @@ SPHINXBUILD   = uv run --project .. sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter

docs/users-guide/modelsetup.rst

@@ -16,7 +16,7 @@ assumes the user is more experienced in running travel demand models and profici
 used ActivitySim or has not used recent versions of ActivitySim. More detailed instructions for installing
 and running ActivitySim are also available in this Users Guide.
 
-* Use the :ref:`Pre-packaged Installer`
+* Use the :ref:`pre-packaged installer`
 * :ref:`Run the Primary Example`
 * Placeholder (Edit model input files, configs, as needed)
 
@@ -88,9 +88,12 @@ Installing ActivitySim
 
 There are two recommended ways to install ActivitySim:
 
-1. Using a :ref:`Pre-packaged Installer` (recommended for users who do not need to change the Python code)
+1. Using a :ref:`pre-packaged installer`
 
-2. Using a :ref:`Python the uv package and project manager` (recommended for users who need to change/customize the Python code)
+2. Using a :ref:`Python the uv package and project manager`
+
+The first is recommended for users who do not need to change the Python code and are on Windows, 
+and the second is recommended for users who need to change/customize the Python code.
 
 
 Pre-packaged Installer
@@ -130,12 +133,14 @@ environment management including installation and management of Python
 versions and dependency locking. The steps involved are described as follows:
 
 1. Install *uv*. Instructions can be found 
-`here <https://docs.astral.sh/uv/getting-started/installation/>`.
+`here <https://docs.astral.sh/uv/getting-started/installation/>`_.
 
 2. Clone the ActivitySim project using Git. (If Git is not installed, 
-instructions can be found `here <https://git-scm.com/downloads>`.)
+instructions can be found `here <https://git-scm.com/downloads>`_.)
+
+::
 
-  git clone https://github.com/ActivitySim/activitysim.git
+  git clone https://github.com/ActivitySim/activitysim.git  
   cd activitysim
 
 3. Optionally create the virtual environment. This is created automatically 
@@ -146,25 +151,33 @@ want to install the project in a non-editable mode so that users on
 your machine cannot accidentally change the source code, use the 
 `--no-editable` option.) 
 
+::
+
   uv sync --no-editable
 
 4. Run an ActivitySim command using the following. (This will automatically 
 create a virtual environment from the lockfile, if it does not already 
 exist.)
 
+::
+
   uv run ...
 
 For example, run the ActivitySim commandline using the following, which 
 makes sure the code is run within the correct (locked) Python environment. 
 More information about the commandline interface is available in 
 the :ref:`Ways to Run the Model` section.
 
+::
+
   uv run activitysim run -c configs -o output -d data
 
 If you want to run ActivitySim from a directory different than where the 
 code lives, use the `project` option to point *uv* to this project using 
 relative paths:
 
+::
+
   uv run --project relative/path/to/activitysim/code activitysim run -c configs -o output -d data
 
 For more on *uv*, visit https://docs.astral.sh/uv/.

pyproject.toml

@@ -101,6 +101,7 @@ convention = "numpy"
 [dependency-groups]
 dev = [
     "altair",
+    "autodoc_pydantic",
     "asv",  # for benchmarking
     "black==22.12.0,<23",
     "bump2version",  # for making a release