Minor documentation updates (#38)

* add doc build-docs-sphinx

* move docs for-developers under main

* minor docs updates

* change toctree maxdepth

* update CHANGELOG for v0.3.3 release

CHANGELOG.md

@@ -12,7 +12,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 (none)
 
-## \[0.3.2\] - 2024-06-28
+## \[v0.3.3\] - 2024-06-28
+
+### Changed
+
+- Minor documentation updates.
+
+## \[v0.3.2\] - 2024-06-28
 
 ### Added
 
@@ -23,7 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Major documentation reorganization and updates.
 - Rename the PubSub.Consumer parameter batch_maxwait -> batch_max_wait_between_messages for clarity.
 
-## \[0.3.1\] - 2024-06-26
+## \[v0.3.1\] - 2024-06-26
 
 ### Added
 
@@ -42,7 +48,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 - pittgoogle_env.yml file
 
-## \[0.3.0\] - 2024-06-08
+## \[v0.3.0\] - 2024-06-08
 
 ### Added
 
@@ -65,7 +71,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - v0.1 `bigquery` functions.
 - Setup and requirements files that are no longer needed after switching away from Read The Docs.
 
-## \[0.2.0\] - 2023-07-02
+## \[v0.2.0\] - 2023-07-02
 
 ### Added
 

docs/source/index.rst

@@ -3,41 +3,33 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+pittgoogle-client
+=================
+
+`pittgoogle-client` is a python library for accessing astronomy data served by
+`Pitt-Google Alert Broker <https://github.com/mwvgroup/Pitt-Google-Broker>`__.
+Tutorials and examples can be found at
+`Pitt-Google User Demos <https://github.com/mwvgroup/pittgoogle-user-demos>`__.
+If you run into trouble, please
+`open an Issue <https://github.com/mwvgroup/pittgoogle-client/issues>`__.
+
 .. toctree::
-    :maxdepth: 3
-    :hidden:
+    :caption: Overview
+    :maxdepth: 1
 
     main/listings
     Install<main/one-time-setup/install>
     main/one-time-setup/index
     main/faq/index
-
-.. toctree::
-    :caption: For Developers
-    :maxdepth: 3
-    :hidden:
-
-    for-developers/setup-environment
-    for-developers/manage-dependencies-poetry
-    for-developers/release-new-version
+    main/for-developers/index
 
 .. toctree::
     :caption: API Reference
-    :maxdepth: 3
-    :hidden:
+    :maxdepth: 1
 
     api-reference/auth
     api-reference/bigquery
     api-reference/exceptions
     api-reference/pubsub
     api-reference/registry
     api-reference/utils
-
-pittgoogle-client
-=================
-
-`pittgoogle-client` is a python library for accessing astronomy data served by
-`Pitt-Google Alert Broker <https://github.com/mwvgroup/Pitt-Google-Broker>`__.
-
-If you run into trouble, please
-`open an Issue <https://github.com/mwvgroup/pittgoogle-client/issues>`__.

docs/source/main/faq/index.rst

@@ -2,7 +2,7 @@ Frequently Asked Questions
 ==============================================
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 1
 
     cost
     find-project-id

docs/source/main/for-developers/build-docs-sphinx.md

@@ -0,0 +1,31 @@
+# Build Documentation with Sphinx
+
+This page describes how to build documentation locally for testing.
+This is not always needed.
+Our published documentation is built and released automatically when a
+[new package version](release-new-version.md) is released.
+In addition, every PR triggers automatic testing of the documentation build.
+However, those GitHub builds can take awhile and there doesn't seem to be an easy way to actually
+view the built documentation.
+For those reasons, it is sometimes helpful to be able to build the documentation locally.
+
+Follow the setup steps in [Managing Dependencies with Poetry](manage-dependencies-poetry.md) to
+create a conda environment with Poetry installed. Then:
+
+```bash
+# Install pittgoogle dependencies, including those in the "docs" group.
+poetry install --with=docs
+```
+
+Now, `cd` to the docs directory and run `make`:
+
+```bash
+cd docs  # assuming we started in the repo root directory
+
+# Build the documentation
+make clean
+make html
+```
+
+This should have created a file at `docs/build/html/index.html`.
+Open it in a browser to view the built documentation.

docs/source/main/for-developers/index.rst

@@ -0,0 +1,10 @@
+For Developers
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    setup-environment
+    manage-dependencies-poetry
+    build-docs-sphinx
+    release-new-version

docs/source/for-developers/release-new-version.md → docs/source/main/for-developers/release-new-version.md

@@ -11,6 +11,7 @@ When you are ready to release a new version of `pittgoogle-client`, publish to P
     - Under "Choose a tag", enter the version tag as "v" followed by the release version
       ([semantic versioning](https://semver.org/) MAJOR.MINOR.PATCH).
     - Enter the same tag for the release title.
+    - Under "Write", paste in the relevant section of CHANGELOG.md describing the release.
     - Click "Publish release".
 
 Completing step 3 will:

docs/source/main/one-time-setup/authentication.rst

@@ -7,7 +7,7 @@ Authentication for API calls is obtained directly from Google Cloud.
 Two options are implemented in pittgoogle. Complete at least one:
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 1
 
     Service Account (recommended)<self>
     OAuth2<authentication-oauth>

docs/source/main/one-time-setup/index.rst

@@ -6,7 +6,7 @@ One-Time Setup
 Using pittgoogle-client to interact with cloud resources requires the following one-time setup tasks:
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 1
 
     Install pittgoogle-client<install>
     Setup a Google Cloud Project<project>