Repository: mwvgroup/Pitt-Google-Broker (language: python)

Issue:
Bugfix: Docs -- RTD build, RST formatting, and working-notes TOCs
Closes #208 

Included changes:

- Fix the RTD build issue caused by [Drop support for "Use system packages"](https://blog.readthedocs.com/drop-support-system-packages/).
- Update python 3.7 -> 3.12 (build env).
- Explicitly install broker_utils requirements in docs/requirements.txt.
- Lint RST.
- Fix working-notes TOC trees so they display all .md and .rst files.

Note that there are still plenty of warnings in the build logs for things like broken links that need to be fixed. This PR just gets the docs building again and updates TOC trees to make sure they display all pages.


Discussion / hints:

Fix patch:
diff --git a/.readthedocs.yml b/.readthedocs.yaml
similarity index 81%
rename from .readthedocs.yml
rename to .readthedocs.yaml
index 0db10518..ec1bb84b 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yaml
@@ -4,6 +4,12 @@
 # Required
 version: 2
 
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
@@ -13,10 +19,5 @@ formats: []
 
 # Set the version of Python and requirements required to build the docs
 python:
-  version: 3.7
-  system_packages: true
   install:
     - requirements: docs/requirements.txt
-    - method: setuptools
-      path: .
-
diff --git a/broker/broker_utils/broker_utils/avro_schemas/load.py b/broker/broker_utils/broker_utils/avro_schemas/load.py
index 437f978e..efbabfc3 100644
--- a/broker/broker_utils/broker_utils/avro_schemas/load.py
+++ b/broker/broker_utils/broker_utils/avro_schemas/load.py
@@ -1,14 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
-"""The ``avro_schemas.load`` module loads and returns Avro schemas.
-
+"""
+The ``avro_schemas.load`` module loads and returns Avro schemas.
 
-REGISTERED_SCHEMAS = [
-    "elasticc.v0_9.alert.avsc",
-    "elasticc.v0_9.brokerClassification.avsc",
-    "elasticc.v0_9_1.alert.avsc",
-    "elasticc.v0_9_1.brokerClassification.avsc",
-]
+To view a list of registered schema names, use: ``avro_schemas.load.REGISTERED_SCHEMAS``
 """
 
 from importlib.resources import path as rpath
diff --git a/broker/broker_utils/broker_utils/gcp_utils.py b/broker/broker_utils/broker_utils/gcp_utils.py
index c8a6ec33..facd7a0a 100644
--- a/broker/broker_utils/broker_utils/gcp_utils.py
+++ b/broker/broker_utils/broker_utils/gcp_utils.py
@@ -355,16 +355,19 @@ def query_bigquery(
             Optional job config to send with the query.
 
     Example query:
-        ``
+
+    .. code-block:: python
+
         query = (
             f'SELECT * '
             f'FROM `{dataset_project_id}.{dataset}.{table}` '
             f'WHERE objectId={objectId} '
         )
-        ``
 
     Examples of working with the query_job:
-        ``
+
+    .. code-block:: python
+
         # Cast it to a DataFrame:
         query_job.to_dataframe()
 
@@ -372,7 +375,6 @@ def query_bigquery(
         for r, row in enumerate(query_job):
             # row values can be accessed by field name or index
             print(f"objectId={row[0]}, candid={row['candid']}")
-        ``
     """
     if project_id is None:
         project_id = project_id_default
diff --git a/broker/broker_utils/broker_utils/math.py b/broker/broker_utils/broker_utils/math.py
index ce3b5bac..8d9e3fe6 100644
--- a/broker/broker_utils/broker_utils/math.py
+++ b/broker/broker_utils/broker_utils/math.py
@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
 """The ``math`` module contains mathematical transforms for survey data."""
+
 from typing import Tuple
 
 import numpy as np
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 5d6a8ce3..c8587fe0 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,22 +1,3 @@
-# # pgb-utils
-# apache_beam[gcp]
-# aplpy
-# astropy==3.2.1
-# astropy-healpix==0.6
-# beautifulsoup4==4.8
-# # google-auth
-# # google-api-core
-# # google-apitools
-# google-cloud-bigquery
-# google-cloud-logging
-# google-cloud-pubsub
-# google-cloud-storage
-# matplotlib
-# numpy
-# pandas
-# tabulate
-# typing
-
 # Needed for building docs
 docutils<0.17  # render lists properly
 myst-parser
@@ -24,3 +5,23 @@ sphinx
 sphinx-copybutton
 sphinx_autodoc_typehints
 sphinx_rtd_theme
+
+# Needed to build docs for broker_utils
+# It would be better not to duplicate this but it's is an easy way to get RTD to build,
+# and broker_utils really needs to be removed from this repo anyway (#158).
+# ---- Below here copied from broker/broker_utils/requirements.txt ----
+# If you have trouble with astropy, jinja2, MarkupSafe, and/or soft_unicode
+# Try using a Conda environment with Python 3.7 e.g.,
+# $ conda create -n pgb python=3.7
+astropy
+fastavro
+# google-api-core
+google-cloud-bigquery
+google-cloud-logging
+google-cloud-storage>=1.38
+google-cloud-pubsub
+numpy
+pandas
+PyYAML>=5.3
+six>=1.15  # bigquery requires
+typing
diff --git a/docs/source/api/broker-utils/avro-schemas.rst b/docs/source/api/broker-utils/avro-schemas.rst
index b2aca04e..2eb79d3d 100644
--- a/docs/source/api/broker-utils/avro-schemas.rst
+++ b/docs/source/api/broker-utils/avro-schemas.rst
@@ -1,5 +1,5 @@
 broker_utils.avro_schemas
-========================
+=========================
 
 .. automodule:: broker.broker_utils.broker_utils.avro_schemas.load
    :members:
diff --git a/docs/source/broker/architecture-diagrams.md b/docs/source/broker/architecture-diagrams.md
index 1a7278f6..86f61079 100644
--- a/docs/source/broker/architecture-diagrams.md
+++ b/docs/source/broker/architecture-diagrams.md
@@ -1,6 +1,6 @@
 # Architecture Diagrams
 
-## Current
+## 2022 (now outdated)
 
 ![Current Architecture](architecture-current.svg)
 
diff --git a/docs/source/broker/components/broker-schedule.rst b/docs/source/broker/components/broker-schedule.rst
index ee1e01b8..916457f7 100644
--- a/docs/source/broker/components/broker-schedule.rst
+++ b/docs/source/broker/components/broker-schedule.rst
@@ -22,8 +22,8 @@ Uptime Check Schedules
 
 .. note::
 
-	The following setup is cumbersome and has the further disadvantage that it has
-    to be scheduled separately from the VMs. Fixing it is part of 
+    The following setup is cumbersome and has the further disadvantage that it has
+    to be scheduled separately from the VMs. Fixing it is part of
     `#109 <https://github.com/mwvgroup/Pitt-Google-Broker/issues/109>`__.
 
 The Cloud Function ``check_cue_response`` checks whether instances are running or
@@ -60,6 +60,7 @@ To update the existing policy, or create a new one, see:
     <https://cloud.google.com/monitoring/alerts/using-alerting-api>`__
 -   `Managing notification channels
     <https://cloud.google.com/monitoring/support/notification-options>`__
+
 Where to look if there's a problem
 ----------------------------------
 
diff --git a/docs/source/broker/setup-ref.rst b/docs/source/broker/setup-ref.rst
index fd15994c..16dbb10e 100644
--- a/docs/source/broker/setup-ref.rst
+++ b/docs/source/broker/setup-ref.rst
@@ -45,7 +45,7 @@ Install broker-utils
 ---------------------
 
 Our broker-utils python library contains many functions that are helpful in working both alerts and GCP services.
-It can be installed using 
+It can be installed using
 (you may want to activate a Conda environment before installing):
 
 .. code-block:: bash
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1f17e33f..69b3a991 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,11 +10,6 @@ The Pitt-Google Broker is a cloud-based alert distribution service designed to p
 
 The Pitt-Google Broker runs on the `Google Cloud Platform <https://cloud.google.com/>`_ (GCP) and is currently focused on processing and serving alerts from the `Zwicky Transient Facility <https://www.ztf.caltech.edu/>`_ (ZTF), and extending broker capabilities using ZTF, the LSST Alert Simulator, and the DECam Alliance for Transients (DECAT) stream.
 
-.. .. toctree::
-..    :hidden:
-..
-..    Overview<self>
-
 .. toctree::
    :hidden:
    :maxdepth: 1
@@ -50,13 +45,3 @@ The Pitt-Google Broker runs on the `Google Cloud Platform <https://cloud.google.
 
    working-notes/early-dev/README
    working-notes/troyraen/index
-
-For the current broker-utils API reference, see the `update_broker_utils branch <https://pitt-broker.readthedocs.io/en/u-tjr-update_broker_utils/api/broker-utils/avro-schemas.html>`__.
-
-..
-.. Indices and tables
-.. ==================
-..
-.. * :ref:`genindex`
-.. * :ref:`modindex`
-.. * :ref:`search`
diff --git a/docs/source/working-notes/early-dev/README.md b/docs/source/working-notes/early-dev/README.md
deleted file mode 100644
index 4f41dcce..00000000
--- a/docs/source/working-notes/early-dev/README.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Project Notes
-
-This directory contains various project documents and notes for use by the developers early in the project. 
-
-
-
-## External Links and Resources
-
-#### General
-
-- Project notes: [here](./notes/)
-- Online LSST forum for data managment (DM): [community.lsst.org/](https://community.lsst.org/)
-- LSST-DESC Broker Workshop talks [drive.google.com/...](https://drive.google.com/drive/folders/1sjYXbdwTID3VnzZNAkcjLbjRfpwNaO_n?usp=sharing)
-
-
-
-#### LSST Documents
-
-- Plans and Policies for alert distribution (how will community brokers be chosen?): [ls.st/LDM-612](https://ls.st/LDM-612)
-- Call for letters ofiIntent for community alert brokers (how do I apply to be a community broker?): [ls.st/LDM-682](https://ls.st/LDM-682)
-- LSST alerts: key numbers (how many? how much? how often?): [dmtn-102.lsst.io](https://dmtn-102.lsst.io)
-- Data Products Definition Document (DPDD) (What data will LSST deliver?): [ls.st/dpdd](https://ls.st/dpdd)
-- Prototype schemas: [github.com/lsst-dm/sample-avro-alert](https://github.com/lsst-dm/sample-avro-alert)
-- Kafka-based alert stream: [github.com/lsst-dm/alert_stream](https://github.com/lsst-dm/alert_stream)
-
-
-
-#### ZTF
-
-- Sample alert packets: [ztf.uw.edu/alerts/public/](https://ztf.uw.edu/alerts/public/)
-- Alert packet tools: [zwicky.tf/4t5](https://zwicky.tf/4t5)
-- Alert schema documentation: [zwicky.tf/dm5](https://zwicky.tf/dm5)
-- Detailed pipelines documentation: [zwicky.tf/ykv](https://zwicky.tf/ykv)
-- PASP instrument papers: [zwicky.tf/3w9](https://zwicky.tf/3w9)
-
-
-
-## Internal Resources
-
-- Meeting minutes: [Available on Google Docs](https://docs.google.com/document/d/1h6rNfFttoCKtpXUHnEfWOhzgjI6sxuSPmpTmzpz5qvw/edit#heading=h.44dh10bplhuh).
-- Letter of Intent (LOI): [Available on Overleaf ](https://www.overleaf.com/project/5c86ae8f6183b337fc5c9ec9)
-
-- Competitive products survey:
-  - [ANTARES.md](./competitive_product_survey/ANTARES.md)
-  - [Lasair.md](./competitive_product_survey/Lasair.md)
-- Notes from the DESC broker workshop: [desc_broker_workshop.md](desc_broker_workshop.md)
-- Cross matching: [cross_matching.md](./cross_matching.md)
-- Tutorial to setting up Cloud Pub/Sub: [pubsub-tutorial.md](./pubsub-tutorial.md)
diff --git a/docs/source/working-notes/early-dev/README.rst b/docs/source/working-notes/early-dev/README.rst
new file mode 100644
index 00000000..fe534c39
--- /dev/null
+++ b/docs/source/working-notes/early-dev/README.rst
@@ -0,0 +1,78 @@
+Project Notes
+=============
+
+This directory contains various project documents and notes for use by
+the developers early in the project.
+
+Directory Table of Contents
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :caption: All Notes
+
+   *
+   */*
+
+External Links and Resources
+----------------------------
+
+General
+^^^^^^^
+
+-  Project notes: `here <./notes/>`__
+-  Online LSST forum for data managment (DM):
+   `community.lsst.org/ <https://community.lsst.org/>`__
+-  LSST-DESC Broker Workshop talks
+   `drive.google.com/... <https://drive.google.com/drive/folders/1sjYXbdwTID3VnzZNAkcjLbjRfpwNaO_n?usp=sharing>`__
+
+LSST Documents
+^^^^^^^^^^^^^^
+
+-  Plans and Policies for alert distribution (how will community brokers
+   be chosen?): `ls.st/LDM-612 <https://ls.st/LDM-612>`__
+-  Call for letters ofiIntent for community alert brokers (how do I
+   apply to be a community broker?):
+   `ls.st/LDM-682 <https://ls.st/LDM-682>`__
+-  LSST alerts: key numbers (how many? how much? how often?):
+   `dmtn-102.lsst.io <https://dmtn-102.lsst.io>`__
+-  Data Products Definition Document (DPDD) (What data will LSST
+   deliver?): `ls.st/dpdd <https://ls.st/dpdd>`__
+-  Prototype schemas:
+   `github.com/lsst-dm/sample-avro-alert <https://github.com/lsst-dm/sample-avro-alert>`__
+-  Kafka-based alert stream:
+   `github.com/lsst-dm/alert_stream <https://github.com/lsst-dm/alert_stream>`__
+
+ZTF
+^^^
+
+-  Sample alert packets:
+   `ztf.uw.edu/alerts/public/ <https://ztf.uw.edu/alerts/public/>`__
+-  Alert packet tools: `zwicky.tf/4t5 <https://zwicky.tf/4t5>`__
+-  Alert schema documentation: `zwicky.tf/dm5 <https://zwicky.tf/dm5>`__
+-  Detailed pipelines documentation:
+   `zwicky.tf/ykv <https://zwicky.tf/ykv>`__
+-  PASP instrument papers: `zwicky.tf/3w9 <https://zwicky.tf/3w9>`__
+
+Internal Resources
+------------------
+
+-  Meeting minutes: `Available on Google
+   Docs <https://docs.google.com/document/d/1h6rNfFttoCKtpXUHnEfWOhzgjI6sxuSPmpTmzpz5qvw/edit#heading=h.44dh10bplhuh>`__.
+
+-  Letter of Intent (LOI): `Available on
+   Overleaf <https://www.overleaf.com/project/5c86ae8f6183b337fc5c9ec9>`__
+
+-  Competitive products survey:
+
+   -  `ANTARES.md <./competitive_product_survey/ANTARES.md>`__
+   -  `Lasair.md <./competitive_product_survey/Lasair.md>`__
+
+-  Notes from the DESC broker workshop:
+   `desc_broker_workshop.md <desc_broker_workshop.md>`__
+
+-  Cross matching: `cross_matching.md <./cross_matching.md>`__
+
+-  Tutorial to setting up Cloud Pub/Sub:
+   `pubsub-tutorial.md <./pubsub-tutorial.md>`__
diff --git a/docs/source/working-notes/early-dev/competitive_product_survey/ANTARES.md b/docs/source/working-notes/early-dev/competitive_product_survey/ANTARES.md
index e266e169..294122b2 100644
--- a/docs/source/working-notes/early-dev/competitive_product_survey/ANTARES.md
+++ b/docs/source/working-notes/early-dev/competitive_product_survey/ANTARES.md
@@ -1,29 +1,31 @@
-# ANTARES
+# docs/source/working-notes/early-dev/competitive_product_survey/ANTARES.md
 
-###### The Arizona-NOAO Temporal Analysis and Response to Events System
+## ANTARES
 
+The Arizona-NOAO Temporal Analysis and Response to Events System
 
 
-## Overview
+
+### Overview
 
 *"The primary goal of the ANTARES prototype is to recognize ‘interesting’ alerts that are uncharacteristic of known kinds of transients and variables so that follow-up observations for further elucidation (which are likely to be time-critical) can be done as soon as permissible."*
 
 
 
-- Only forwards alerts that pass image-quality tests.  
+- Only forwards alerts that pass image-quality tests.
   - Real bogus score `ztf_rb` < 0.55 are ignored
 
-  - Alerts with bad pixels (`ztf_nbad` > 0) or a large difference in aperture vs PSF magnitudes (`ztf_magdiff` outside of the range -0.1 to 0.1) are ignored. 
-  - Alerts with poor seeing (`ztf_fwhm` > 5.0 arcsec) or elongated sources (`ztf_elong` > 1.2) are ignored 
+  - Alerts with bad pixels (`ztf_nbad` > 0) or a large difference in aperture vs PSF magnitudes (`ztf_magdiff` outside of the range -0.1 to 0.1) are ignored.
+  - Alerts with poor seeing (`ztf_fwhm` > 5.0 arcsec) or elongated sources (`ztf_elong` > 1.2) are ignored
 - All alerts, regardless of the above cuts, are stored in case they are needed for future processing.
 - Waits for two detections to run science since alerts with only one detection are likely to be unknown Solar System objects
 - Associates each alert with the nearest point of known past measurements in a 1" radius. (The `Locus`)
 
 
 
-## Services
+### Services
 
-- A search engine for the alerts database 
+- A search engine for the alerts database
 - Slack notifications of new alerts in your stream/watchlist of interest (Done)
 - Object watchlists ([Done](http://antares.noao.edu/watchlist))
 - Ability to add custom Python filters directly through their website ([Done](http://antares.noao.edu/filters))
@@ -34,15 +36,15 @@
 
 
 
-## Architecture
+### Architecture
 
 - Alerts are ingested and then cross-matched and associated with previously discovered objects. Any alerts associated with more than one object can be replicated to consider each association
   - Object association with the AstroObject Database is performed by calculating each object’s 20-digit index on a hierarchical triangular mesh (HTM, Kunszt et al., 2001) used to cover the sphere (Szalay et al., 2007). The quad-tree search of the HTM is implemented in SciSQL. Association radii are different for the various astronomical catalogs, as the resolution of surveys in different regions of the electromagnetic spectrum can vary by orders of magnitude.
-- To determine if an object is interesting, it is compared against the *Touchstone* (defined below) using a variation of the nearest-neighbor search. 
+- To determine if an object is interesting, it is compared against the *Touchstone* (defined below) using a variation of the nearest-neighbor search.
 - As part of ranking alerts, objects fall into four categories: known-knowns, known-unknowns, unknown-knowns, and unknown-unknowns.
   - known-knowns: We have seen before and understand.
-  - Known-unknowns: Predicted to exist that have not yet been observed. 
-  - Unknown-knowns: Objects observed, but not yet understood. 
+  - Known-unknowns: Predicted to exist that have not yet been observed.
+  - Unknown-knowns: Objects observed, but not yet understood.
   - Unknown-unknowns: Newly discovered, unpredicted objects.
 - Alerts are then passed through filters and sent out to the alert streams.
 - Each alert is treated independently. Spatially correlated alerts (such as multiply lensed systems or extended objects like light echoes) will have to be evaluated in a different system. Moving objects are also not considered.
@@ -51,14 +53,14 @@
   1. **Aggregated AstroObject Catalog**: Represents current astronomical knowledge. This information is used to annotate the incoming alerts with relevant data if the alert can be associated with a known object
   2. **Locus-Aggregated Annotated Alerts**: All alerts processed by ANTARES with annotations, including AstroObject association, feature derivation, and filtering results.
   3. **Touchstone**: A database of properties and features for known or predicted kinds of variable astronomical sources based on the Kepler survey and eventually Gaia.
-  4. **Annotated Coalesced Alerts**: Database of all alerts processed by ANTARES with annotations and ranking 
+  4. **Annotated Coalesced Alerts**: Database of all alerts processed by ANTARES with annotations and ranking
   5. A few others that are not relevant here.
 
 
 
-## Example Use Cases
+### Example Use Cases
 
-1. **Counterparts to Gravitational Wave Sources**: There is extensive literature predicting the optical characteristics of a GW source. For an aLIGO alert, the expectation is that there will not be a previously detected source, but that there will be a host galaxy. There may not be enough information from early, limited observations, so a list of likely alerts may be produced, rather than a single, sure thing. 50% of aLIGO events will have localizations ≤ 20 square degrees. LSST has a 10 square degree field-of-view. 
+1. **Counterparts to Gravitational Wave Sources**: There is extensive literature predicting the optical characteristics of a GW source. For an aLIGO alert, the expectation is that there will not be a previously detected source, but that there will be a host galaxy. There may not be enough information from early, limited observations, so a list of likely alerts may be produced, rather than a single, sure thing. 50% of aLIGO events will have localizations ≤ 20 square degrees. LSST has a 10 square degree field-of-view.
 
 2. **Tidal Disruption Events (TDEs)**: If a star moves too close to a massive black hole, the tidal forces can essentially rip it apart. These TDEs will also appear as alerts in the LSST data stream with characteristics quite similar to AGN.
 
@@ -66,13 +68,13 @@
 
 
 
-## Value-added Products
+### Value-added Products
 
 Primarily forwarding value the raw ZTF alerts with the addition of some internal bookkeeping data and crossmatching. Work is underway to add real-time classifications of transient sources. For more information see [The ZTF Science Data System (ZSDS) Explanatory Supplement](http://web.ipac.caltech.edu/staff/fmasci/ztf/ztf_pipelines_deliverables.pdf) (page 60).
 
 
 
-## Links
+### Links
 
 #### Websites
 
@@ -94,5 +96,3 @@ Primarily forwarding value the raw ZTF alerts with the addition of some internal
    time-domain alerts (Saha et al. 2016)](https://arxiv.org/abs/1611.05914)
 
 3. [Machine Learning-based Brokers for Real-time Classification of the LSST Alert Stream (Narayan et al. 2018)](https://arxiv.org/abs/1801.07323)
-
-   
diff --git a/docs/source/working-notes/early-dev/competitive_product_survey/Lasair.md b/docs/source/working-notes/early-dev/competitive_product_survey/Lasair.md
index c9ec1e9e..c306ab18 100644
--- a/docs/source/working-notes/early-dev/competitive_product_survey/Lasair.md
+++ b/docs/source/working-notes/early-dev/competitive_product_survey/Lasair.md
@@ -1,12 +1,14 @@
-# Lasair Overview
+# docs/source/working-notes/early-dev/competitive_product_survey/Lasair.md
 
-## Primary Goals
+## Lasair Overview
+
+### Primary Goals
 
 1. Ingest the ZTF public alert stream into a relational database
 2. Condense the alerts into possible objects
 3. Produce lightcurves of these objects and reliable cross-matches to star and galaxy catalogs for possible follow-up
 
-## Assorted Info
+### Assorted Info
 
 - Lasair = “flare” or “flash” in Scots and Irish gaelic
 - The transient alerts broker for the LSST: UK collaboration
@@ -21,7 +23,7 @@
   - Ex: nuclear transients and TDE candidates
   - Ex: SNe candidates—all objects NOT classified as a variable star, AGN, or CV and are not coincident with a Pan-STARRS stellar source
 
-## Data Products
+### Data Products
 
 3 SQL tables as data products
 
@@ -45,7 +47,7 @@
     - Orphans: stationary, transient sources that aren’t associated with a cataloged star or galaxy
   - Maintains an up-to-date crossmatch with the IAU Transient Name Server to quickly identify known transients within the ZTF stream
 
-## Searching Lasair
+### Searching Lasair
 
   - Can use SQL SELECT queries to search their provided tables
   - Few different types of search methods:
@@ -61,7 +63,7 @@
     - An interactive AladinLite display of the region of interest
     -  A table with each of the relevant candidates’ info (i.e., each lightcurve point), taken from the *candidates* table
 
-## Sources
+### Sources
 
 1. Smith, K. W., Williams, R. D., Young, R. D., et al. 2019, RNAAS 3:1
-1. [https://github.com/thespacedoctor/sherlock](https://github.com/thespacedoctor/sherlock)
\ No newline at end of file
+1. [https://github.com/thespacedoctor/sherlock](https://github.com/thespacedoctor/sherlock)
diff --git a/docs/source/working-notes/early-dev/cross_matching.md b/docs/source/working-notes/early-dev/cross_matching.md
index 19298bea..80be756d 100644
--- a/docs/source/working-notes/early-dev/cross_matching.md
+++ b/docs/source/working-notes/early-dev/cross_matching.md
@@ -1,19 +1,20 @@
+# docs/source/working-notes/early-dev/cross_matching.md
 
-# To Do
+## To Do
 - [ ] Start with [astroquery](https://astroquery.readthedocs.io/en/latest/)
 
 
-# Astroquery
+## Astroquery
 <!-- fs -->
 [astroquery](https://astroquery.readthedocs.io/en/latest/)
 "Astroquery is a set of tools for querying astronomical web forms and databases... All astroquery modules are supposed to follow the same API. In its simplest form, the API involves queries based on coordinates or object names."
 
-## astroquery.xmatch
+### astroquery.xmatch
 [XMatch Getting started](https://astroquery.readthedocs.io/en/latest/xmatch/xmatch.html#module-astroquery.xmatch)
 [XMatchClass](https://astroquery.readthedocs.io/en/latest/api/astroquery.xmatch.XMatchClass.html#astroquery.xmatch.XMatchClass.query)
 XMatch uses the CDS xMatch service: [CDS xMatch service documentation](http://cdsxmatch.u-strasbg.fr/xmatch/doc/)
 
-## install:
+### install:
 ``` bash
 conda install -c astropy astroquery
 ```
@@ -22,13 +23,13 @@ conda install -c astropy astroquery
 
 
 
-# Possible XM Tools
+## Possible XM Tools
 <!-- fs -->
 
 - [ ] Start with [astroquery](https://astroquery.readthedocs.io/en/latest/)
 
 
-## Summary of tools
+### Summary of tools
 
 "Astronomical data fusion tool based on PostgreSQL" would be great, but I can't actually find the software.
 
@@ -42,7 +43,7 @@ Probably the best options (see below for details):
 - [The Large Survey Database (LSD)](http://research.majuric.org/public/project/lsd/) (python)
 
 
-## Tools details
+### Tools details
 <!-- fs -->
 
 - [ ] mcatCS: (multi-band catalog Cross-matching Scheme, 2019)
@@ -85,7 +86,7 @@ Probably the best options (see below for details):
 <!-- fe possible XM tools -->
 
 
-# Notes from paper: Gaia Data Release 1. Cross-match with external catalogues Algorithm and results
+## Notes from paper: Gaia Data Release 1. Cross-match with external catalogues Algorithm and results
 <!-- fs -->
 
 Paper:
@@ -96,7 +97,7 @@ Marrese+17
 
 XM = cross matching
 
-## Possible Features
+### Possible Features
 
 Can match one-to-one, one-to-many, or many-to-one. In the case of identifying host galaxy of supernova we probably want one-to-one?
 
@@ -124,7 +125,7 @@ Important consideration:
 Many of the possible features can improve matching of generic objects at the cost of poor matching for peculiar objects. My guess is that we will deal with many 'peculiar' objects..?
 
 
-## Techniques
+### Techniques
 
 Possible option: http://docs.astropy.org/en/stable/_modules/astropy/coordinates/matching.html
 
@@ -138,7 +139,7 @@ Figure of merit:
 
 <!-- fe notes from Gaia paper -->
 
-## MARS Links
+### MARS Links
 
 [MARS website](https://mars.lco.global/help/)
 [Git Repo](https://github.com/LCOGT/ztf-alert-server)
diff --git a/docs/source/working-notes/early-dev/desc_broker_workshop.md b/docs/source/working-notes/early-dev/desc_broker_workshop.md
index 805d9884..825ab91f 100644
--- a/docs/source/working-notes/early-dev/desc_broker_workshop.md
+++ b/docs/source/working-notes/early-dev/desc_broker_workshop.md
@@ -1,11 +1,13 @@
-# DESC Broker Workshop
+# docs/source/working-notes/early-dev/desc_broker_workshop.md
+
+## DESC Broker Workshop
 
 This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](https://drive.google.com/drive/folders/1sjYXbdwTID3VnzZNAkcjLbjRfpwNaO_n?usp=sharing)
 
 
-## Thursday Session 1: Science Vision and Precursor Surveys
+### Thursday Session 1: Science Vision and Precursor Surveys
 
-### Lessons learned from microlensing follow-up (Rachel Street)
+#### Lessons learned from microlensing follow-up (Rachel Street)
 - Microlensing requires rapid followup (Usually < 10 alerts per day)
 - You need redundancy in followup locations to deal with weather and down time
 - Data should be shared in real time with clear publication guidelines
@@ -18,7 +20,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### Black Hole Microlensing with Parallax (Nathan Golovich @ LLNL)
+#### Black Hole Microlensing with Parallax (Nathan Golovich @ LLNL)
 
 - Discussed why this topic is scientifically interesting
 - How will the alert system handel long time scale signals with weak signal to noise?
@@ -27,12 +29,12 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### Microlensing with ZTF: Breaking in Spin with Brokers (Michael Medford @ LBNL)
+#### Microlensing with ZTF: Breaking in Spin with Brokers (Michael Medford @ LBNL)
 
 - **Z**TF **A**lert **P**acket **I**nspection **T**ool
 - Capture
   - Ingest ZTF alert packet data through Kafka consumer
-  - Cross-match detections into long duration light-curves 
+  - Cross-match detections into long duration light-curves
 - Detect
   -  Regularly filter for ongoing and completed microlensing events
   - Remove false positives, mainly variable stars
@@ -51,18 +53,18 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### The ZTF Coadd Facility (Danny Goldstein @ Caltech)
+#### The ZTF Coadd Facility (Danny Goldstein @ Caltech)
 
 - Combines images from multiple observations to create deeper stacks.
 - Reduces functional cadence, but increases the number of discovered objects
 
 
 
-## Thursday Session 2: LSST Prompt Processing Data Products
+### Thursday Session 2: LSST Prompt Processing Data Products
 
 
 
-### LSST Prompt Data Products (Melissa Graham @ U. of Washington)
+#### LSST Prompt Data Products (Melissa Graham @ U. of Washington)
 
 - Online LSST forum for DM [here](https://community.lsst.org/). See [ls.st/dmtn-102](ls.st/dmtn-102) for alert stream numbers.
 - Alert production process:
@@ -73,7 +75,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
   - Alert packet assembled for SNR>5 detections
   - Alert sent to community
 - Alert packet contents for 60s releases:
-  - Difference image source parameters 
+  - Difference image source parameters
     - ID, coordinate, flux, shape, SNR, association with static and moving cataloges
   - Difference image object parameters
     - ~12 month history of proper motion, parallax, mean flux, variability parameters, and ID for the latest Data Release deep stacks
@@ -91,7 +93,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### Plans and Policies for LSST Alert Distribution (Eric Bellm @ U. of Washington)
+#### Plans and Policies for LSST Alert Distribution (Eric Bellm @ U. of Washington)
 
 - Key documents:
   - Plans and Policies for Alert Distribution (how will community brokers be chosen?) [ls.st/LDM-612](ls.st/LDM-612)
@@ -108,7 +110,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
   - No requirement to make products world public
   - Will favor proposals that offer these!
 - The selection process has two phases: an open call for Letters of Intent, and an invitational call for full proposals.
-- Brokers must demonstrate adequate resources 
+- Brokers must demonstrate adequate resources
   - Large inbound and outbound network bandwidth (the full alert
     stream is a few TB/night)
   - Petabytes of disk capacity
@@ -141,9 +143,9 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-## Thursday Session 3: Broker Components
+### Thursday Session 3: Broker Components
 
-### Connexions between LSST-DESC Broker and Machine Learning (Emille E. O. Ishida @ Université Clermont-Auvergne)
+#### Connexions between LSST-DESC Broker and Machine Learning (Emille E. O. Ishida @ Université Clermont-Auvergne)
 
 - Complete representation is not possible in astronomical training sets for machine learning (ML).
 - One solution is to implement an active learning technique where human inspection is used to supplement the training process.
@@ -154,7 +156,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### RAPID - Real-time Automated Photometric IDentification (Daniel Muthukrishna @ University of Cambridge)
+#### RAPID - Real-time Automated Photometric IDentification (Daniel Muthukrishna @ University of Cambridge)
 
 - Trained on PLAsTiCC data set.
 - SN identification is very similar to voice analysis. Quiet followed by a sudden increase in signal on multiple frequencies.
@@ -163,9 +165,9 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-## Thursday Session 4: Infrastructure in Development 
+### Thursday Session 4: Infrastructure in Development
 
-### Antares (Gauthem):
+#### Antares (Gauthem):
 
 - Classify objects, provide summary of object properties, and allow users to apply personalized filters
 - Expected to scale easily to LSST
@@ -177,7 +179,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### Lasair ()
+#### Lasair ()
 
 - Backend development in place - still building front end api.
 - Running on jupyter hub.
@@ -185,9 +187,9 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-## Friday Session 5: Additional Talks and a Group Discussion on “Charting the Course Forward”
+### Friday Session 5: Additional Talks and a Group Discussion on “Charting the Course Forward”
 
-### NERSC support (Debbie Bard @ NERSC)
+#### NERSC support (Debbie Bard @ NERSC)
 
 - Cori is generation NERSC-8. NERSC-9 (Perlmutter) comes online in 2020 and includes the addition of GPUs instead of just CPUs.
 - NERSC 9 is targeted at data applications and simulations
@@ -200,13 +202,13 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-### PLAsTiCC update (Renae):
+#### PLAsTiCC update (Renae):
 
 - Data and models will be made public
 
 
 
-### SkyPortal (Stéfan van der Walt @ Berkely)
+#### SkyPortal (Stéfan van der Walt @ Berkely)
 
 - Sky Portal is an open source data access portal
 - Scalable from laptop to cloud services
@@ -216,7 +218,7 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 
 
 
-## Random Thoughts
+### Random Thoughts
 
 - Any broker system needs to have redundancies to protect against downtime
 - Don't just build systems in advance - train people to use them in advance
@@ -232,4 +234,4 @@ This document provides notes on the LSST-DESC Broker Workshop. [Link to Talks](h
 - Log the version of each analysis step so you can track changes over time.
 - SkyPortal can be used as a front end (more scalable, astronomy focused alternative to Flask, Django, etc...)
 - Follow scheduler: https://tomtoolkit.github.io
-- DESC doesn't want its own broker but is concerned about understanding the selection function and classification effeciency well.
\ No newline at end of file
+- DESC doesn't want its own broker but is concerned about understanding the selection function and classification effeciency well.
diff --git a/docs/source/working-notes/early-dev/pubsub-tutorial.md b/docs/source/working-notes/early-dev/pubsub-tutorial.md
index 0ae4facf..1ca0f20a 100755
--- a/docs/source/working-notes/early-dev/pubsub-tutorial.md
+++ b/docs/source/working-notes/early-dev/pubsub-tutorial.md
@@ -1,6 +1,8 @@
-# Pub/Sub Step-by-Step (note: _not_ a tutorial to pub\_sub\_client)
+# docs/source/working-notes/early-dev/pubsub-tutorial.md
 
-## Initial Setup
+## Pub/Sub Step-by-Step (note: _not_ a tutorial to pub\_sub\_client)
+
+### Initial Setup
 
 You'll need to install some additional requirements to use Pub/Sub. The main requirement is the `pubsub_v1` package, installable via
 
@@ -24,17 +26,17 @@ You'll need to activate your APIs/Services and get an authentication JSON file:
 > Note: The service account has an associated "name", of sorts, that follows an email address format. It goes: `SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com`, where you set the SERVICE\_ACCOUNT\_NAME and the PROJECT\_ID is listed in the JSON file. The PROJECT\_ID is not the same as the project number. This email address is also listed in the JSON file as "client\_email".
 
 - Then, make sure the *JSON* bullet option is still selected and click **Create**. This will create a JSON authentication file and download it to your computer.
-- Locate this file, rename it however you see fit, and move it wherever you like, though do take note of this file path. Add a line in your .bash_profile file and restart your terminal session: 
+- Locate this file, rename it however you see fit, and move it wherever you like, though do take note of this file path. Add a line in your .bash_profile file and restart your terminal session:
 
 ``` bash
 export GOOGLE_APPLICATION_CREDENTIALS="FILE_PATH/FILE_NAME.json"
 ```
-	
+
 - To check if this variable was set correctly, type `echo $GOOGLE_APPLICATION_CREDENTIALS` in your terminal to see if the correct file path is displayed. If so, you should be authenticated to use GCP from your current terminal session.
 - You should also see the service account key listed on the *Credentials* page, and there is a trashcan icon on the right in case you need to delete these authentication credentials. *Note: doing so will make the JSON file useless.*
 
-## Topics and Subscriptions
-### Starting a Topic
+### Topics and Subscriptions
+#### Starting a Topic
 
 By python script:
 ``` python
@@ -61,7 +63,7 @@ gcloud pubsub topics create my_topic
 ```
 > Note: It may take a few seconds for the topic to appear on your project's *Topics* page, so be patient.
 
-### Starting a Subscription
+#### Starting a Subscription
 
 By python script:
 ``` python
@@ -92,7 +94,7 @@ You can set the acknowledgment deadline time *#* (in seconds) using the option `
 
 > Note: It may take a few seconds for the subscription to appear on your project's *Subscriptions* page, so be patient.
 
-### Setting Permissions for Local Work
+#### Setting Permissions for Local Work
 
 To publish and retrieve messages from Python scripts on your laptop, the permissions need to be slightly altered on the topic and subscription (I'm still not sure why).
 
@@ -105,13 +107,13 @@ To publish and retrieve messages from Python scripts on your laptop, the permiss
 - Since it inherited ownership, it should appear in a drop-down list below the *Add member* box; selecting the first entry worked for me, but the second may as well, I'm not sure.
 - Select the same "Role > Project > Owner" and click **Save**. You'll notice that under the *inherited* column, the service account will now say **mixed**.
 
-Repeat for the subscriptions you'd like to use, where the only change is in selecting the subscriptions by checkbox from your project's *Subscriptions* page. 
+Repeat for the subscriptions you'd like to use, where the only change is in selecting the subscriptions by checkbox from your project's *Subscriptions* page.
 
-### Publishing and Retrieving Messages
+#### Publishing and Retrieving Messages
 
 Some of the code below is largely taken from [this quickstart guide](https://cloud.google.com/pubsub/docs/quickstart-client-libraries?refresh=1&pli=1#pubsub-quickstart-publish-python), and here is the guide for using [gcloud command-line tool](https://cloud.google.com/pubsub/docs/quickstart-cli?refresh=1).
 
-#### Publishing
+##### Publishing
 
 Via python script, assuming the topic has already been made:
 
@@ -146,7 +148,7 @@ Via GCP Console Commands:
  gcloud pubsub topics publish my-topic --message hello
  ```
 
-#### Retrieve/Pull Messages
+##### Retrieve/Pull Messages
 
 Via python script, assuming the subscription has already been made:
 
@@ -181,12 +183,12 @@ Via GCP Console Commands:
  ```
 The keyword `--limit=#` can be added between `--auto-ack` and `my_sub` to limit the number of messages you pull.
 
-## Ordering Messages
+### Ordering Messages
 Pub/Sub attempts to deliver a message to a subscriber once and in order, but this cannot be guaranteed. A new feature called **message ordering** has been implemented to help resolve this issue, with documentation on [publishing](https://cloud.google.com/pubsub/docs/publisher#using_ordering_keys) and more general info [here](https://cloud.google.com/pubsub/docs/ordering). Unfortunately, this is in beta for a handful of the APIs and in a closed alpha for others, including python (as of 8/6/2020). Updating your install of `google-cloud-pubsub` to the lastest version (8/62020: 1.7.0) will download code that has support for the new keyword, but it will not allow you to use the keyword when publishing. The following instructions are for future reference when these features become available, either in beta or through general availability.
 
 First, enable message ordering for the subscription.
 
-By GCP GUI: 
+By GCP GUI:
 
 - When creating the subscription, select the checkbox to enable message ordering.
 - Edit an existing subscription's settings and check the box to enable message ordering.
diff --git a/docs/source/working-notes/early-dev/troy/google_fellowship.md b/docs/source/working-notes/early-dev/troy/google_fellowship.md
index d18ff2f2..fea3e6eb 100644
--- a/docs/source/working-notes/early-dev/troy/google_fellowship.md
+++ b/docs/source/working-notes/early-dev/troy/google_fellowship.md
@@ -1,3 +1,5 @@
+# docs/source/working-notes/early-dev/troy/google_fellowship.md
+
 [Google fellowship](https://ai.google/research/outreach/phd-fellowship/)
 - "Applications for the 2020 program will open on November 1st, 2019."
     - "Fellowship nominations are received in November each year. Awardees are notified by March and publicly announced in April."
diff --git a/docs/source/working-notes/early-dev/troy/rarePUevents.md b/docs/source/working-notes/early-dev/troy/rarePUevents.md
index 51874dda..9a5cf3cf 100644
--- a/docs/source/working-notes/early-dev/troy/rarePUevents.md
+++ b/docs/source/working-notes/early-dev/troy/rarePUevents.md
@@ -1,4 +1,6 @@
-# LSST Science Book
+# docs/source/working-notes/early-dev/troy/rarePUevents.md
+
+## LSST Science Book
 "LSST will enable early detection of prototype cases for a number of
 theoretically predicted explosive transients which we’ve already discussed, including orphan GRB
 afterglows, accretion induced collapse events, fall-back and pair-instability supernovae, and the so
diff --git a/docs/source/working-notes/early-dev/troy/troy_notes.md b/docs/source/working-notes/early-dev/troy/troy_notes.md
index 7b002317..b415b374 100644
--- a/docs/source/working-notes/early-dev/troy/troy_notes.md
+++ b/docs/source/working-notes/early-dev/troy/troy_notes.md
@@ -1,4 +1,6 @@
-# TOM proposal clustering
+# docs/source/working-notes/early-dev/troy/troy_notes.md
+
+## TOM proposal clustering
 <!-- fs TOM proposal clustering -->
 ```bash
 conda create -n pgb python=3.7
@@ -474,11 +476,11 @@ features = e_features.get_features()
 <!-- fe TOM proposal clustering -->
 
 
-# Use cases
+## Use cases
 <!-- fs use cases -->
 look in to [astrorapid](https://pypi.org/project/astrorapid/) for classification
 
-## SN
+### SN
 <!-- fs SN -->
 What user wants:
     * Prob(SN type...)
@@ -500,7 +502,7 @@ XM features:
     - redshift
 <!-- fe SN -->
 
-## CV (white dwarf with non-degen companion)
+### CV (white dwarf with non-degen companion)
 <!-- fs CV -->
 [Prospects for detection of detached double white dwarf binaries with Gaia, LSST and LISA](arxiv:1703.02555)
 expect periodicity? can we do better than Lomb-Scargle?
@@ -589,14 +591,14 @@ _Datasets._
 <!-- fe use cases -->
 
 
-# Notes and To Do
+## Notes and To Do
 <!-- fs -->
 [Google fellowship](https://ai.google/research/outreach/phd-fellowship/)
 - ? need "Research/dissertation proposal (recommended length 4-5 pages, no longer than 8)"
 
 incorporate Rongpu's DECaLS catalog by end of August
 
-## Chicago talk
+### Chicago talk
 ```python
 import numpy as np
 from matplotlib import pyplot as plt
@@ -613,7 +615,7 @@ for alert in alert_list:
 plt.hist(np.array(sn))
 ```
 
-## Create value_added module
+### Create value_added module
 <!-- fs value added -->
 *Korriban environment not working... delete all PB environments and start from scratch*
 
@@ -693,7 +695,7 @@ predictions = classify.rapid(light_curves, plot=False, use_redshift=True)
 <!-- fe value added -->
 
 
-## Create RAPID module
+### Create RAPID module
 <!-- fs -->
 
 ```python
@@ -733,7 +735,7 @@ Need to:
 
 <!-- fe ## Create RAPID module -->
 
-## July 9
+### July 9
 <!-- fs -->
 1. Have RAPID classifying SN with host galaxy info by July 23rd.
     * write it to accept dictionary as input (AVRO files are priority, but should be able to accept BigQuery input with some wrapper function.)
@@ -746,7 +748,7 @@ Need to:
 
 <!-- fe ## July 9 -->
 
-## Classifications meeting prep (RAPID and SuperNNova)
+### Classifications meeting prep (RAPID and SuperNNova)
 <!-- fs -->
 [RAPID](https://astrorapid.readthedocs.io)
 [ZTF Avro Schemas](https://zwickytransientfacility.github.io/ztf-avro-alert/schema.html)
@@ -761,7 +763,7 @@ Meeting prep:
 <!-- fe ## Classifications meeting prep (RAPID and SuperNNova) -->
 
 
-## Testing pub_sub branch. PASSED.
+### Testing pub_sub branch. PASSED.
 <!-- fs -->
 GCP topic: troy_test_topic
 GCP subscription: troy_test_subscript
@@ -833,38 +835,27 @@ print("Received and acknowledged {} messages. Done.".format(len(ack_ids)))
 <!-- fe # Notes and To Do -->
 
 
-# Info
+## Info
 <!-- fs INFO -->
-# GIT Info
+### GIT Info
 [repo](https://github.com/mwvgroup/Pitt-Google-Broker)
 git@github.com:mwvgroup/Pitt-Google-Broker.git
 [read the docs](https://pitt-broker.readthedocs.io/en/latest/index.html)
 
-# DATA Info
+### DATA Info
 To use data stored on Korriban: in broker/ztf_archive/\_download\_data.py, set the variable:
 ZTF_DATA_DIR = Path('/Users/troyraen/Korriban/Documents/Pitt-Broker/broker/ztf_archive/data')
 
-# ZTF Info
+### ZTF Info
 [alert schema](https://zwickytransientfacility.github.io/ztf-avro-alert/schema.html)
 
-
-# GCP Account Info
-Project name: pitt-google-broker-prototype
-Project ID: ardent-cycling-243415
-Project number: 591409139500
-
-Service Account: tjraen-owner@ardent-cycling-243415.iam.gserviceaccount.com
-project_id = 'ardent-cycling-243415'
-topic_name = 'troy_test_topic'
-subscription_name = 'troy_test_subscript'
-
 <!-- fe INFO -->
 
-# Code
+## Code
 <!-- fs -->
 
 
-## Download ZTF Data
+### Download ZTF Data
 <!-- fs -->
 ```python
 from broker import ztf_archive as ztfa
@@ -879,7 +870,7 @@ for alert in iter_alerts():
 <!-- fe ## Download ZTF Data -->
 
 
-## Astroquery
+### Astroquery
 <!-- fs -->
 ```python
 
@@ -935,7 +926,7 @@ table = XMatch.query(cat1=open(fradec), cat2='vizier:II/246/out', \
 
 
 
-## Download and look at alerts
+### Download and look at alerts
 <!-- fs -->
 ```python
 from matplotlib import pyplot as plt
@@ -977,7 +968,7 @@ plt.show()
 ```
 <!-- fe download and look at alerts -->
 
-## Remove and reinstall Conda environment
+### Remove and reinstall Conda environment
 <!-- fs -->
 ```bash
 conda remove --name pitt_broker --all
@@ -1007,8 +998,9 @@ Beetled59Expounded84crucially18dilemma's55protesting
 <!-- fe # Code -->
 
 
-# Supernovae Handbook
-## Ch 12 Observational and Physical Classification of Supernovae (9/13/19)
+## Supernovae Handbook
+
+### Ch 12 Observational and Physical Classification of Supernovae (9/13/19)
 Classifications based on spectroscopy at peak brightness.
 1st cut: is there hydrogen? yes = Type II, no = Type I
 Type I cut: SiII = Ia, none = 1b (has He) or 1c (no He) (mag ~-19)
@@ -1026,14 +1018,14 @@ Note: 7000-10000 Angstroms, water vapor absorption gets strong
 
 <!-- fs ARCHIVE -->
 
-## 6/11/19
+### 6/11/19
 <!-- fs -->
 travel funding
 use cases
 data studio
 <!-- fe ## 6/4/19 -->
 
-## 6/4/19
+### 6/4/19
 <!-- fs -->
 travel funding
 use cases
@@ -1041,7 +1033,7 @@ data studio
 <!-- fe ## 6/4/19 -->
 
 
-## 5/28/19
+### 5/28/19
 <!-- fs -->
 questions to answer:
 planning to fail with Messier objects (15 arcmin)
@@ -1061,7 +1053,7 @@ user watch list - (galactic variable stars, identified strong lensing systems, )
             - Ia, Ic, variable, AGN, galaxy
 <!-- fe ## 5/28/19 -->
 
-## 5/21/19
+### 5/21/19
 <!-- fs -->
 1. choose a small handful of catalogs to focus on
     - SDSS (photometery and spectroscopy)
@@ -1083,7 +1075,7 @@ user watch list - (galactic variable stars, identified strong lensing systems, )
     - period
 <!-- fe ## 5/21/19 -->
 
-## April-ish 19
+### April-ish 19
 <!-- fs -->
 [SDSS catalog](bruno/users/cnm37/Skyserver_3e5_stars_mags.csv, ~/Korriban/Documents/Pitt-Broker/mock_stream/data/Skyserver_3e5_stars_mags.csv)
 - [x] rsync -avzn -e ssh tjr63@bruno.phyast.pitt.edu:pitt-broker/Skyserver_3e5_stars_mags.csv ~/Korriban/Documents/Pitt-Broker/mock_stream/data/.
@@ -1092,7 +1084,7 @@ moving data dir to Korriban:
 - [x] rsync -avz /Users/troyraen/Documents/Pitt-Broker/mock_stream/data ~/Korriban/Documents/Pitt-Broker/mock_stream/
 <!-- fe ## April-ish 19 -->
 
-# DESC call re: LSST call for brokers (4/10/19)
+## DESC call re: LSST call for brokers (4/10/19)
 <!-- fs -->
 [Official Notes](https://docs.google.com/document/d/1hsQd4JDPgscUkGEw6m8qL_Fxy8JyRvMSBYHzDePXlMc/edit)
 
diff --git a/docs/source/working-notes/early-dev/troy_notes.md b/docs/source/working-notes/early-dev/troy_notes.md
deleted file mode 100644
index 637b5bfe..00000000
--- a/docs/source/working-notes/early-dev/troy_notes.md
+++ /dev/null
@@ -1,332 +0,0 @@
-
-# Use cases
-<!-- fs -->
-look in to [astrorapid](https://pypi.org/project/astrorapid/) for classification
-
-## SN
-What user wants:
-    * Prob(SN type...)
-    - selection function
-    - host galaxy
-        - mass
-        - SFR
-How to classify:
-    - astrorapid
-Primary catalogs to match on:
-    - SDSS, maybe BOSS (northern sky)
-    - DES (southern)
-    - ZTF
-XM features:
-    * RA, DEC
-    - classification
-    - errors (more specifically... ?)
-    - external survey depth
-    - redshift
-
-## CV (white dwarf with non-degen companion)
-What user wants:
-    * Prob(CV)
-    - period
-    - companion information
-How to classify:
-    - more light in xray than visible, but we probably won't have this info
-    - check for existing ML or other algorithms
-Primary catalogs to match on:
-    - GAIA (more likely to contain companion than WD)
-    - APOGEE (more likely to contain companion than WD)
-    - Ritter & Kolb 2003 (CV catalog)
-XM features:
-    * RA, DEC
-    - classification
-    - errors (more specifically... ?)    
-
-<!-- fe # Use cases -->
-
-
-# Notes and To Do
-<!-- fs -->
-
-## July 9
-<!-- fs -->
-1. Have RAPID classifying SN with host galaxy info by July 23rd.
-    * write it to accept dictionary as input (AVRO files are priority, but should be able to accept BigQuery input with some wrapper function.)
-    - mwebv: milky way excess b-v color (dust extinction)
-    - mjd: modified julian date
-    - flux and error: convert PSF mags
-    - zeropoint: magzpsci. ask Daniel
-    - photflag: ask Daniel
-2. Test pub/sub. Try to write automated tests.. input, calling fncs or code trying to test, and expected output.
-
-<!-- fe ## July 9 -->
-
-## RAPID
-<!-- fs -->
-[RAPID](https://astrorapid.readthedocs.io)
-[ZTF Avro Schemas](https://zwickytransientfacility.github.io/ztf-avro-alert/schema.html)
-Meeting prep:
-* RAPID and SuperNNova
-* RAPID more straightforward so setting that up.
-    - but requires redshift info... standard process seems to be to use host gal redshift.
-    - not sure what they do when there's no identified host.
-* Need training dataset. Have galaxy set from Graham and SN, etc. set from PLAsTICC.
-    - not sure if I'm allowed to use either for this purpose.
-
-
-
-<!-- fe ## RAPID -->
-
-
-## Testing pub_sub branch
-<!-- fs -->
-GCP topic: troy_test_topic
-GCP subscription: troy_test_subscript
-
-```python
-from broker import ztf_archive as ztfa
-# ztfa.download_data_date(year=2018, month=6, day=26)
-ztfa.download_recent_data(max_downloads=10)
-
-from google.cloud import pubsub_v1
-project_id = 'ardent-cycling-243415'
-topic_name = 'troy_test_topic'
-publisher = pubsub_v1.PublisherClient()
-topic_path = publisher.topic_path(project_id, topic_name)
-for n in range(1, 4):
-    data = u'Message number {}'.format(n)
-    # Data must be a bytestring
-    data = data.encode('utf-8')
-    # When you publish a message, the client returns a future.
-    future = publisher.publish(topic_path, data=data)
-    print('Published {} of message ID {}.'.format(data, future.result()))
-print('Published messages.')
-
-subscription_name = 'troy_test_subscript'
-subscriber = pubsub_v1.SubscriberClient()
-subscription_path = subscriber.subscription_path(project_id, subscription_name)
-max_messages = 10
-response = subscriber.pull(subscription_path, max_messages=max_messages)
-ack_ids = []
-for received_message in response.received_messages:
-    print("Received: {}".format(received_message.message.data))
-    ack_ids.append(received_message.ack_id)
-subscriber.acknowledge(subscription_path, ack_ids)
-print("Received and acknowledged {} messages. Done.".format(len(ack_ids)))
-
-# from pub_sub_client import message_service as ms
-# ms.publish_alerts('pitt-broker', topic_name, alerts)
-# alerts     (list): The list of ZTF alerts to be published (as returned by alert_acquistion.get_alerts())
-# ms.subscribe_alerts('pitt-broker', subscription_name, max_alerts=1)
-
-```
-<!-- fe ## Testing pub_sub branch -->
-
-
-## 6/11/19
-<!-- fs -->
-travel funding
-use cases
-data studio
-<!-- fe ## 6/4/19 -->
-
-## 6/4/19
-<!-- fs -->
-travel funding
-use cases
-data studio
-<!-- fe ## 6/4/19 -->
-
-
-## 5/28/19
-<!-- fs -->
-questions to answer:
-planning to fail with Messier objects (15 arcmin)
-what are our use cases
-minimum viable product/protype
-user watch list - (galactic variable stars, identified strong lensing systems, ) - could define own matching radius. Notify user of alert match and upcoming expected observations.
-*want to set up user web interface*
-    - list of alerts + value added
-    - upcoming pointing regions
-    - DIA object page
-        - all related alerts
-        - postage stamps
-        - light curve: interactive, connect plot points to data tables
-        - cross matches
-            - whether spectra exist
-        - classification confidence as a function of time
-            - Ia, Ic, variable, AGN, galaxy
-<!-- fe ## 5/28/19 -->
-
-## 5/21/19
-<!-- fs -->
-1. choose a small handful of catalogs to focus on
-    - SDSS (photometery and spectroscopy)
-        - SEGUE (MW stars)
-        - Sloan Supernova Survey (1a)
-        - APOGEE (IR spec of MW stars)
-        - BOSS and eBOSS (LRGs)
-        - MaNGA (nearby galaxy spectroscopy)
-    - WISE (IR all sky survey, near earth objects, star clusters) - ask Ross
-    - GAIA (MW stars)
-    - 2MASS (galaxies, star clusters, stars, galaxies behind MW, low mass stars)
-    - Chandra Source Catalog (X-ray sources, AGN, SNe remnants, X-ray binaries)
-2. evaluate store catalogs in Big Query
-3. think about what we want to use in the xmatch
-    - RA/DEC
-    - redshift
-    - object type/classification
-    - photometery/colors
-    - period
-<!-- fe ## 5/21/19 -->
-
-## April-ish 19
-<!-- fs -->
-[SDSS catalog](bruno/users/cnm37/Skyserver_3e5_stars_mags.csv, ~/Korriban/Documents/Pitt-Broker/mock_stream/data/Skyserver_3e5_stars_mags.csv)
-- [x] rsync -avzn -e ssh tjr63@bruno.phyast.pitt.edu:pitt-broker/Skyserver_3e5_stars_mags.csv ~/Korriban/Documents/Pitt-Broker/mock_stream/data/.
-
-moving data dir to Korriban:
-- [x] rsync -avz /Users/troyraen/Documents/Pitt-Broker/mock_stream/data ~/Korriban/Documents/Pitt-Broker/mock_stream/
-<!-- fe ## April-ish 19 -->
-
-<!-- fe # Notes and To Do -->
-
-
-
-# Questions
-
-- [ ] don't see any redshift info in alert_data['candidate']
-- [ ] easier way to change DATA_DIR (download_data.py, parse_data.py)
-
-# GCP Account Info
-Project name: pitt-google-broker-prototype
-Project ID: ardent-cycling-243415
-Project number: 591409139500
-
-Service Account: tjraen-owner@ardent-cycling-243415.iam.gserviceaccount.com
-project_id = 'ardent-cycling-243415'
-topic_name = 'troy_test_topic'
-subscription_name = 'troy_test_subscript'
-
-# Code
-<!-- fs -->
-
-## Astroquery
-<!-- fs -->
-```python
-
-# Get RA and DEC from alerts and write to file:
-import pandas as pd
-def get_alerts_RA_DEC(fout=None):
-    """ Iterate through alerts and grab RA, DEC.
-        Write data to file with format compatible with astroquery.xmatch.query().
-
-        fout = string, path to save file.
-
-        Returns the alert data as a Pandas DataFrame.
-    """
-
-    data_list = []
-    for a, alert in enumerate(iter_alerts()):
-        alert_id = alert['candid']
-        alert_data = get_alert_data(alert_id)
-
-        dat = {}
-        dat['alert_id'] = alert_id
-        dat['ra'] = alert_data['candidate']['ra']
-        dat['dec'] = alert_data['candidate']['dec']
-        data_list.append(dat)
-
-        if a>1000: break
-
-    print('creating df')
-    df = pd.DataFrame(data_list)
-
-    if fout is not None:
-        print('writing df')
-        df.to_csv(fout, sep=',', columns=['alert_id','ra','dec'], header=True, index=False)
-    else:
-        return df
-
-    return None
-
-fradec = 'mock_stream/data/alerts_radec.csv'
-get_alerts_RA_DEC(fout=fradec)
-
-# Use Astroquery to query CDS xMatch service
-from astropy import units as u
-from astroquery.xmatch import
-table = XMatch.query(cat1=open(fradec), cat2='vizier:II/246/out', \
-                    max_distance=5 * u.arcsec, colRA1='ra', colDec1='dec')
-# with the current data, this matches 818 out of 1002 in fradec
-# table.columns gives ['angDist','alert_id','ra','dec','2MASS','RAJ2000','DEJ2000','errHalfMaj','errHalfMin','errPosAng','Jmag','Hmag','Kmag','e_Jmag','e_Hmag','e_Kmag','Qfl','Rfl','X','MeasureJD']
-
-```
-
-<!-- fe Astroquery -->
-
-
-
-## Download and look at alerts
-<!-- fs -->
-```python
-from matplotlib import pyplot as plt
-from mock_stream import download_data
-from mock_stream import get_alert_data
-from mock_stream import get_number_local_alerts
-from mock_stream import iter_alerts
-from mock_stream import number_local_releases
-from mock_stream import plot_stamps
-
-# Download data from ZTF. By default only download 1 day
-# Note: Daily releases can be as large as several G
-download_data(max_downloads=1)
-
-# Retrieve the number of daily releases that have been downloaded
-print(number_local_releases())
-
-# Retrieve the number of alerts that have been downloaded
-# from all combined daily releases.
-print(get_number_local_alerts())
-
-# Iterate through local alert data
-for alert in iter_alerts():
-    alert_id = alert['candid']
-    print(alert_id)
-    break
-
-# Get alert data for a specific id
-alert_id = 833156294815015029
-alert_data = get_alert_data(alert_id)
-RA, DEC = alert_data['candidate']['ra'], alert_data['candidate']['dec']
-# print(alert_data)
-
-
-# Plot stamp images for alert data
-fig = plot_stamps(alert_data)
-plt.show()
-
-```
-<!-- fe download and look at alerts -->
-
-<!-- fe -->
-
-
-# DESC call re: LSST call for brokers (4/10/19)
-<!-- fs -->
-[Official Notes](https://docs.google.com/document/d/1hsQd4JDPgscUkGEw6m8qL_Fxy8JyRvMSBYHzDePXlMc/edit)
-
-No DESC working groups have expressed need for alerts on timescales < 24 hours
-    => no driver for DESC to develop a broker
-One thing DESC needs that is not part of 60sec alert stream is..?
-
-Value added products DESC needs:
-    - classify events scientifically
-    - triggering followup
-
-LSST considering offering alert stream in cloud.
-
-DESC will focus on 24hr and yearly data releases.
-
-__Useful quality of Broker: _light_ filtering of alerts__
-
-
-<!-- fe DESC call re: LSST call for brokers -->
diff --git a/docs/source/working-notes/troyraen/AbrilCVs/ASAS-SN/README.md b/docs/source/working-notes/troyraen/AbrilCVs/ASAS-SN/README.md
index 767cea6f..a92690bf 100644
--- a/docs/source/working-notes/troyraen/AbrilCVs/ASAS-SN/README.md
+++ b/docs/source/working-notes/troyraen/AbrilCVs/ASAS-SN/README.md
@@ -1,3 +1,5 @@
-# CV catalog
+# docs/source/working-notes/troyraen/AbrilCVs/ASAS-SN/README.md
 
-Downloaded from [ASAS-SN Variable Stars Database](https://asas-sn.osu.edu/variables) 
+## CV catalog
+
+Downloaded from [ASAS-SN Variable Stars Database](https://asas-sn.osu.edu/variables)
diff --git a/docs/source/working-notes/troyraen/AbrilCVs/J_MNRAS_492_L40/catalog_condensed.md b/docs/source/working-notes/troyraen/AbrilCVs/J_MNRAS_492_L40/catalog_condensed.md
index c586c234..299dd375 100644
--- a/docs/source/working-notes/troyraen/AbrilCVs/J_MNRAS_492_L40/catalog_condensed.md
+++ b/docs/source/working-notes/troyraen/AbrilCVs/J_MNRAS_492_L40/catalog_condensed.md
@@ -1,3 +1,5 @@
+# docs/source/working-notes/troyraen/AbrilCVs/J_MNRAS_492_L40/catalog_condensed.md
+
 ## Create `catalog_condensed.dat`
 
 - Calculate HEALPix indexes of CV catalog.
diff --git a/docs/source/working-notes/troyraen/AbrilCVs/README.md b/docs/source/working-notes/troyraen/AbrilCVs/README.md
index 7af60022..d091d060 100644
--- a/docs/source/working-notes/troyraen/AbrilCVs/README.md
+++ b/docs/source/working-notes/troyraen/AbrilCVs/README.md
@@ -1,4 +1,6 @@
-# AbrilCVs: CV Catalog from Abril 2020
+# docs/source/working-notes/troyraen/AbrilCVs/README.md
+
+## AbrilCVs: CV Catalog from Abril 2020
 
 - [Abril 2020](https://ui.adsabs.harvard.edu/abs/2020MNRAS.492L..40A/abstract)
 - [CV catalog on CDS](https://cdsarc.cds.unistra.fr/viz-bin/cat?J/MNRAS/492/L40) (downloaded to this dir)
@@ -20,7 +22,7 @@
     - Periods of hours. could you predict the magnitude based on different periods, and then check whether alert is consistent? or are the uncertainties too big? mags, period.
 
 
-## Catalog
+### Catalog
 
 ```python
 import os
@@ -78,7 +80,7 @@ abrildf = pd.read_fwf(fcat, names=names, header=None, index=None)
 
 ```
 
-## Calculate HEALPix indexes of CV catalog and use to xmatch
+### Calculate HEALPix indexes of CV catalog and use to xmatch
 
 Calculate indexes
 
@@ -149,7 +151,7 @@ stop = timeit.default_timer()
 print('Time: ', stop - start)
 ```
 
-## Try TNS CVs
+### Try TNS CVs
 
 ```python
 # get positions of TNS CVs
@@ -177,7 +179,7 @@ for _, cv in abrildf.iterrows():
             matches[alert['objectId']] = (alert, cv)
 ```
 
-## Try some ASAS-SN data
+### Try some ASAS-SN data
 
 ```python
 # load asassn
@@ -194,7 +196,7 @@ for _, cv in abrildf.iterrows():
 ```
 
 
-## Test Cloud Run module
+### Test Cloud Run module
 
 ```python
 from broker_utils import gcp_utils
diff --git a/docs/source/working-notes/troyraen/AbrilCVs/exporation_for_linea_talk.md b/docs/source/working-notes/troyraen/AbrilCVs/exporation_for_linea_talk.md
index 351e0357..d91ba8aa 100644
--- a/docs/source/working-notes/troyraen/AbrilCVs/exporation_for_linea_talk.md
+++ b/docs/source/working-notes/troyraen/AbrilCVs/exporation_for_linea_talk.md
@@ -1,4 +1,6 @@
-# Exploration for LIneA talk - Dec 2, 2021
+# docs/source/working-notes/troyraen/AbrilCVs/exporation_for_linea_talk.md
+
+## Exploration for LIneA talk - Dec 2, 2021
 
 ```python
 from matplotlib import pyplot as plt
diff --git a/docs/source/working-notes/troyraen/AllWISE/README.md b/docs/source/working-notes/troyraen/AllWISE/README.md
index 6ebeff31..5f181174 100644
--- a/docs/source/working-notes/troyraen/AllWISE/README.md
+++ b/docs/source/working-notes/troyraen/AllWISE/README.md
@@ -1,4 +1,6 @@
-# AllWISE: Cross match with the AllWISE catalog in BigQuery public datasets
+# docs/source/working-notes/troyraen/AllWISE/README.md
+
+## AllWISE: Cross match with the AllWISE catalog in BigQuery public datasets
 
 Outline:
 - [Create resources and deploy to Cloud Run](#create-resources-and-deploy-to-cloud-run)
@@ -17,7 +19,7 @@ External links:
 - [Instructions to create resources with pubsub trigger](https://cloud.google.com/run/docs/triggering/pubsub-push#command-line_1)
 
 
-## Create resources and deploy to Cloud Run
+### Create resources and deploy to Cloud Run
 
 Allow Pub/Sub to create authentication tokens in the project:
 
@@ -109,7 +111,7 @@ sub_path = subscriber.subscription_path(PROJECT_ID, subscription)
 subscriber.create_subscription(name=sub_path, topic=topic_path)
 ```
 
-## Work out the cross match
+### Work out the cross match
 
 ```python
 from google.cloud import bigquery
@@ -222,7 +224,7 @@ aw_dict = df.to_dict(orient='records')
 
 ```
 
-### Article: Querying the Stars with BigQuery GIS
+#### Article: Querying the Stars with BigQuery GIS
 
 https://cloud.google.com/blog/products/data-analytics/querying-the-stars-with-bigquery-gis
 
@@ -254,7 +256,7 @@ ArcSecondDistance(p1 GEOGRAPHY, p2 GEOGRAPHY, d FLOAT64)
 ArcSecondDistance(point, ST_GEOGPOINT(201.5, -2.6), 60)
 
 
-### How long does a query take?
+#### How long does a query take?
 
 Trying to see whether the AllWISE table indexes by some ID.
 There are (at least) 3 ID columns
@@ -300,7 +302,7 @@ for awcol, xmcol in coldict.items():
             SELECT {awcol}
             FROM `{project_id}.{dataset}.{table}`
             WHERE {awcol}='{df.loc[0,xmcol]}'
-        """        
+        """
     start = timeit.default_timer()
     resultdict[f'{awcol} (all cols)'] = query_job = gcp_utils.query_bigquery(query).to_dataframe()
     stop = timeit.default_timer()
@@ -320,7 +322,7 @@ for awcol, xmcol in coldict.items():
             SELECT {awcol}
             FROM `{project_id}.{dataset}.{table}`
             WHERE spt_ind=200102013 AND {awcol}='{df.loc[0,xmcol]}'
-        """        
+        """
     start = timeit.default_timer()
     resultdict[f'{awcol} (spt_ind)'] = query_job = gcp_utils.query_bigquery(query).to_dataframe()
     stop = timeit.default_timer()
@@ -328,7 +330,7 @@ for awcol, xmcol in coldict.items():
     print('Time: ', stop - start)
 ```
 
-## Copy AllWISE table and add HEALPix column
+### Copy AllWISE table and add HEALPix column
 
 - [x] copy table
 - [ ] add HEALPix
@@ -351,7 +353,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="<your/path/to/servicecredentialsauthkey.j
 gcloud config set project "$project_id"
 ```
 
-### Copy table
+#### Copy table
 
 Uses the BigQuery transfer service.
 
@@ -383,7 +385,7 @@ bq query \
   'QUERY_STATEMENT'
 ```
 
-### Add HEALPix
+#### Add HEALPix
 
 Setup
 
diff --git a/docs/source/working-notes/troyraen/AllWISE/cloud_run/README.md b/docs/source/working-notes/troyraen/AllWISE/cloud_run/README.md
index 36cd6c41..d44a2109 100644
--- a/docs/source/working-notes/troyraen/AllWISE/cloud_run/README.md
+++ b/docs/source/working-notes/troyraen/AllWISE/cloud_run/README.md
@@ -1,4 +1,6 @@
-# Cross match with AllWISE
+# docs/source/working-notes/troyraen/AllWISE/cloud_run/README.md
+
+## Cross match with AllWISE
 
 This module cross matches alerts with the AllWISE catalog in BigQuery's public datasets.
 
diff --git a/docs/source/working-notes/troyraen/HEALPix.md b/docs/source/working-notes/troyraen/HEALPix.md
index 533470d3..fcbc4949 100644
--- a/docs/source/working-notes/troyraen/HEALPix.md
+++ b/docs/source/working-notes/troyraen/HEALPix.md
@@ -1,4 +1,6 @@
-# HEALPix
+# docs/source/working-notes/troyraen/HEALPix.md
+
+## HEALPix
 
 - [http://healpix.jpl.nasa.gov/](http://healpix.jpl.nasa.gov/)
     - [https://healpix.jpl.nasa.gov/pdf/intro.pdf](https://healpix.jpl.nasa.gov/pdf/intro.pdf)
@@ -7,7 +9,7 @@
 
 - [Splitting the Sky - HTM and HEALPix](https://ui.adsabs.harvard.edu/abs/2001misk.conf..638O/abstract) ([alt link](https://www.researchgate.net/publication/226874931_Splitting_the_sky_-_HTM_and_HEALPix))
 
-## `astropy-healpix`
+### `astropy-healpix`
 
 [docs](https://astropy-healpix.readthedocs.io/en/latest/)
 
diff --git a/docs/source/working-notes/troyraen/RTD.md b/docs/source/working-notes/troyraen/RTD.md
index 1cd55f9b..2238ce70 100644
--- a/docs/source/working-notes/troyraen/RTD.md
+++ b/docs/source/working-notes/troyraen/RTD.md
@@ -1,4 +1,6 @@
-# Read The Docs
+# docs/source/working-notes/troyraen/RTD.md
+
+## Read The Docs
 
 - [Sphinx](https://www.sphinx-doc.org/en/master/index.html)
 
@@ -8,5 +10,6 @@ pip install sphinx
 sphinx-quickstart docs
 
 # sphinx-build -b html source build
+make clean
 make html
 ```
diff --git a/docs/source/working-notes/troyraen/Rubin-DPO.md b/docs/source/working-notes/troyraen/Rubin-DPO.md
index b2e46efc..999f3c67 100644
--- a/docs/source/working-notes/troyraen/Rubin-DPO.md
+++ b/docs/source/working-notes/troyraen/Rubin-DPO.md
@@ -1,12 +1,14 @@
-# Rubin DPO
+# docs/source/working-notes/troyraen/Rubin-DPO.md
 
-## TAP
+## Rubin DPO
+
+### TAP
 
 - [PyVO](https://pyvo.readthedocs.io/en/latest/index.html)
 - [get TAP service. source code for DP0 notebook](https://github.com/lsst-sqre/rubin-jupyter-lab/blob/master/rubin_jupyter_utils/lab/notebook/catalog.py)
 - [DP0 notebook 6: Comparing_Object_and_Truth_Tables](https://data.lsst.cloud/nb/user/troyraen/lab/tree/notebooks/tutorial-notebooks/06_Comparing_Object_and_Truth_Tables.ipynb)
 - [DP0 notebook 2: Intermediate_TAP_Query](https://data.lsst.cloud/nb/user/troyraen/lab/tree/notebooks/tutorial-notebooks/02_Intermediate_TAP_Query.ipynb)
-- [RSP API aspect](https://data.lsst.cloud/api-aspect) 
+- [RSP API aspect](https://data.lsst.cloud/api-aspect)
 
 Much of this code is taken from the DP0 notebooks.
 
diff --git a/docs/source/working-notes/troyraen/SuperNNova/README.md b/docs/source/working-notes/troyraen/SuperNNova/README.md
index 7356c6ac..9390badd 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/README.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/README.md
@@ -1,8 +1,10 @@
-# SuperNNova: Implementing SuperNNova Classifier
+# docs/source/working-notes/troyraen/SuperNNova/README.md
+
+## SuperNNova: Implementing SuperNNova Classifier
 
 SuperNNova Links:
 - [docs](https://supernnova.readthedocs.io/en/latest/index.html)
 - [github](https://github.com/supernnova/SuperNNova)
-- [arXiv paper](https://arxiv.org/pdf/1901.06384.pdf)  
+- [arXiv paper](https://arxiv.org/pdf/1901.06384.pdf)
 
 See other files in this directory for development, deployment, validation, etc.
diff --git a/docs/source/working-notes/troyraen/SuperNNova/not_saving_to_bigquery.md b/docs/source/working-notes/troyraen/SuperNNova/not_saving_to_bigquery.md
index 3518b974..f35b93c4 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/not_saving_to_bigquery.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/not_saving_to_bigquery.md
@@ -1,4 +1,6 @@
-# SuperNNova doesn't seem to be saving results to BigQuery. What's going on?
+# docs/source/working-notes/troyraen/SuperNNova/not_saving_to_bigquery.md
+
+## SuperNNova doesn't seem to be saving results to BigQuery. What's going on?
 
 ```python
 table = 'metadata'
diff --git a/docs/source/working-notes/troyraen/SuperNNova/recreate-bq-table.md b/docs/source/working-notes/troyraen/SuperNNova/recreate-bq-table.md
index be01a999..a3c728f9 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/recreate-bq-table.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/recreate-bq-table.md
@@ -1,3 +1,7 @@
+# docs/source/working-notes/troyraen/SuperNNova/recreate-bq-table.md
+
+## Recreate BigQuery Table
+
 Changed column name pred_class -> predicted_class.
 Want to change name in production instance without losing data.
 
diff --git a/docs/source/working-notes/troyraen/SuperNNova/snn_build_cloud_fnc.md b/docs/source/working-notes/troyraen/SuperNNova/snn_build_cloud_fnc.md
index 42e41607..018d8720 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/snn_build_cloud_fnc.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/snn_build_cloud_fnc.md
@@ -1,6 +1,8 @@
-# SuperNNova - build, deploy, test the Cloud Function
+# docs/source/working-notes/troyraen/SuperNNova/snn_build_cloud_fnc.md
 
-## Test the Cloud Function pieces locally
+## SuperNNova - build, deploy, test the Cloud Function
+
+### Test the Cloud Function pieces locally
 
 ```bash
 export GCP_PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -26,7 +28,7 @@ snn_msg = gcp_utils.pull_pubsub('test')[0]
 gcp_utils.insert_rows_bigquery(bq_table, [snn_dict])
 ```
 
-## Local, full test
+### Local, full test
 
 ```bash
 conda create -n snn python=3.7
@@ -81,7 +83,7 @@ for r, row in enumerate(snn_queryjob):
 ```
 This works.
 
-## Deploy Cloud Function
+### Deploy Cloud Function
 
 ```bash
 survey="ztf"
@@ -97,9 +99,13 @@ gcloud functions deploy "$classify_snn_CF_name" \
     --trigger-topic "$classify_snn_trigger_topic" \
     --set-env-vars TESTID="$testid",SURVEY="$survey"
 ```
+
 This errors out with:
-```ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Build failed: Build error details not available.Please check the logs at https://console.cloud.google.com/cloud-build/builds;region=us-central1/d782dfbb-285d-44aa-a164-040e48660089?project=591409139500. Please visit https://cloud.google.com/functions/docs/troubleshooting#build for in-depth troubleshooting documentation for build related errors.
+
 ```
+ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Build failed: Build error details not available.Please check the logs at https://console.cloud.google.com/cloud-build/builds;region=us-central1/d782dfbb-285d-44aa-a164-040e48660089?project=591409139500. Please visit https://cloud.google.com/functions/docs/troubleshooting#build for in-depth troubleshooting documentation for build related errors.
+```
+
 I cannot find any more specific info in the logs or at the provided links.
 The step that it fails on is called "uploading_python_pkg_layer".
 
@@ -137,7 +143,7 @@ See [here](https://stackoverflow.com/questions/55449313/google-cloud-function-py
 
 Fixed by providing a direct URL in requirements.txt.
 
-## Test changes to broker utils
+### Test changes to broker utils
 
 ```bash
 cd /Users/troyraen/Documents/broker/snn/broker/broker_utils
diff --git a/docs/source/working-notes/troyraen/SuperNNova/snn_prelim_exploration.md b/docs/source/working-notes/troyraen/SuperNNova/snn_prelim_exploration.md
index 8cd798bd..cded7eea 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/snn_prelim_exploration.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/snn_prelim_exploration.md
@@ -1,4 +1,6 @@
-# SuperNNova preliminary exploration
+# docs/source/working-notes/troyraen/SuperNNova/snn_prelim_exploration.md
+
+## SuperNNova preliminary exploration
 
 (see also: [snn_train_a_model.md](snn_train_a_model.md))
 
diff --git a/docs/source/working-notes/troyraen/SuperNNova/snn_train_a_model.md b/docs/source/working-notes/troyraen/SuperNNova/snn_train_a_model.md
index 5ca21902..59a27b41 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/snn_train_a_model.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/snn_train_a_model.md
@@ -1,4 +1,6 @@
-# Train a SuperNNova Model
+# docs/source/working-notes/troyraen/SuperNNova/snn_train_a_model.md
+
+## Train a SuperNNova Model
 
 Links
 - [github.com/supernnova/SuperNNova](https://github.com/supernnova/SuperNNova)
@@ -13,7 +15,7 @@ Links
     - random forest from salt2 fits
     - bayesian RNN
 
-## setup
+### setup
 folowing the two quickstarts in readthedocs:
 ```bash
 gcloud compute instances start troy
@@ -34,7 +36,7 @@ pip install supernnova
 ipython
 ```
 
-## train and validate a model using the test set
+### train and validate a model using the test set
 ```bash
 gcloud compute instances start troy
 gcloud compute ssh troy
diff --git a/docs/source/working-notes/troyraen/SuperNNova/snn_validation.md b/docs/source/working-notes/troyraen/SuperNNova/snn_validation.md
index 99de1837..5a952090 100644
--- a/docs/source/working-notes/troyraen/SuperNNova/snn_validation.md
+++ b/docs/source/working-notes/troyraen/SuperNNova/snn_validation.md
@@ -1,4 +1,6 @@
-# SuperNNova validation: Classify known Ia's
+# docs/source/working-notes/troyraen/SuperNNova/snn_validation.md
+
+## SuperNNova validation: Classify known Ia's
 
 1. Download csv from TNS website. ([Search](https://www.wis-tns.org/search) for recent Ia's)
 2. Query database to see what SNN classified these as
@@ -45,7 +47,7 @@ plt.show(block=False)
 
 <img src="snn_results_20211017.png" alt="snn_results_20211017" width="600"/>
 
-### Classify known Ia - Original Test
+#### Classify known Ia - Original Test
 
 The docs indicate that "usually" class0 indicates a Ia and class1 indicates non-Ia,
 but this will depend on how the model was trained.
diff --git a/docs/source/working-notes/troyraen/ZTF-cadence/README.md b/docs/source/working-notes/troyraen/ZTF-cadence/README.md
index e750648c..69f63490 100644
--- a/docs/source/working-notes/troyraen/ZTF-cadence/README.md
+++ b/docs/source/working-notes/troyraen/ZTF-cadence/README.md
@@ -1,4 +1,6 @@
-# ZTF Cadence
+# docs/source/working-notes/troyraen/ZTF-cadence/README.md
+
+## ZTF Cadence
 
 Checking the time delta between ZTF observations of an object.
 
diff --git a/docs/source/working-notes/troyraen/bigquery.md b/docs/source/working-notes/troyraen/bigquery.md
index a9ae417d..d77af1c7 100644
--- a/docs/source/working-notes/troyraen/bigquery.md
+++ b/docs/source/working-notes/troyraen/bigquery.md
@@ -1,4 +1,6 @@
-# BigQuery Links
+# docs/source/working-notes/troyraen/bigquery.md
+
+## BigQuery Links
 
 ```python
 query = """
diff --git a/docs/source/working-notes/troyraen/billing/README.md b/docs/source/working-notes/troyraen/billing/README.md
index 7c643d70..9f8d1da0 100644
--- a/docs/source/working-notes/troyraen/billing/README.md
+++ b/docs/source/working-notes/troyraen/billing/README.md
@@ -1,4 +1,6 @@
-# billing: pitt-google-broker-billing
+# docs/source/working-notes/troyraen/billing/README.md
+
+## billing: pitt-google-broker-billing
 
 - [x] [Export Cloud Billing data to BigQuery](https://cloud.google.com/billing/docs/how-to/export-data-bigquery)
 - [x] Pull some data and create figures
@@ -16,7 +18,7 @@
     - ID: light-cycle-328823
 - Billing account ID: <obtain this from https://console.cloud.google.com/billing/projects>
 
-## Setup: Set environment variables
+### Setup: Set environment variables
 
 ```bash
 # project ids, used to create/manage service accounts, and make queries on the tables
@@ -54,7 +56,7 @@ gcloud components update
 gcloud components update --version 348.0.0
 ``` -->
 
-## Setup for queries and plotting
+### Setup for queries and plotting
 
 ```bash
 # navigate to this directory (replace with your path)
@@ -87,7 +89,7 @@ billing_project_id = os.getenv('GOOGLE_CLOUD_PROJECT', 'light-cycle-328823')
 prod_project_id = os.getenv('GOOGLE_CLOUD_PROJECT2', 'ardent-cycling-243415')
 ```
 
-## Query tables or load dataframes from files
+### Query tables or load dataframes from files
 
 ```python
 # load data from file
@@ -121,7 +123,7 @@ countdf = gcp_utils.query_bigquery(
 ldata = loaded_data(countdf, litebilldf, litebill_ispipelinesku)
 ```
 
-## Look at countdf
+### Look at countdf
 
 ```python
 countdf = countdf.set_index('publish_date').sort_index()
@@ -132,7 +134,7 @@ plt.show(block=False)
 
 ```
 
-## Live pipeline: Bar chart of average cost per sku per million alerts, colored by service
+### Live pipeline: Bar chart of average cost per sku per million alerts, colored by service
 
 ```python
 # keep rows where project and sku => live pipeline
@@ -177,7 +179,7 @@ figures.plot_cost_by_sku(costdf, save=save, cost=cost_per_mil, title=title)
 
 <img src="billing_per_sku_per_million_alerts_ingested.png" alt="billing_per_sku_per_million_alerts_ingested.png"/>
 
-## Not live pipeline: Bar chart of average cost per sku per day, colored by service
+### Not live pipeline: Bar chart of average cost per sku per day, colored by service
 
 ```python
 # keep rows where sku => ~(live pipeline)
@@ -200,7 +202,7 @@ figures.plot_cost_by_sku(costdf, cost=cost_per_day, save=save, title=title)
 
 <img src="billing_per_sku_per_day.png" alt="billing_per_sku_per_day.png"/>
 
-## Live pipeline, Cloud Run: Bar chart of average cost per sku per million alerts, colored by service
+### Live pipeline, Cloud Run: Bar chart of average cost per sku per million alerts, colored by service
 
 ```python
 # keep rows where project and sku => live pipeline and service is Cloud Run
@@ -232,7 +234,7 @@ figures.plot_cost_by_sku(costdf, save=save, cost='cost_per_million_alerts', titl
 
 <img src="billing_per_sku_per_million_alerts_cloud_run.png" alt="billing_per_sku_per_million_alerts_cloud_run.png"/>
 
-## Stacked (services) bar chart of cost vs date
+### Stacked (services) bar chart of cost vs date
 
 ```python
 mycostdf_bydateservice = litebilldf.groupby(['usage_date', 'service']).sum().reset_index()
@@ -258,7 +260,7 @@ plt.show(block=False)
 
 <img src="billing_per_day_and_service.png" alt="billing_per_day_and_service.png"/>
 
-## Bar chart of total cost per sku, colored by service
+### Bar chart of total cost per sku, colored by service
 
 ```python
 import datetime
@@ -277,7 +279,7 @@ figures.plot_cost_by_sku(costdf, save=None)
 
 <img src="billing_per_sku.png" alt="billing_per_sku.png"/>
 
-## Bar chart cost per day, (stack) services
+### Bar chart cost per day, (stack) services
 ```python
 # plot
 my_project = prod_project_id
diff --git a/docs/source/working-notes/troyraen/cloud-run.md b/docs/source/working-notes/troyraen/cloud-run.md
index eb025d54..310e38b5 100644
--- a/docs/source/working-notes/troyraen/cloud-run.md
+++ b/docs/source/working-notes/troyraen/cloud-run.md
@@ -1,4 +1,6 @@
-# Cloud Run info
+# docs/source/working-notes/troyraen/cloud-run.md
+
+## Cloud Run info
 
 - [pubsub trigger](https://cloud.google.com/run/docs/triggering/pubsub-push#command-line_1)
 - [Solving the serverless concurrency problem with Google Cloud Run](https://www.nearform.com/blog/solving-the-serverless-concurrency-problem-with-google-cloud-run/) (Node.js, pooling db connections)
diff --git a/docs/source/working-notes/troyraen/cloudbuild.md b/docs/source/working-notes/troyraen/cloudbuild.md
index 7bc78dae..aa78155f 100644
--- a/docs/source/working-notes/troyraen/cloudbuild.md
+++ b/docs/source/working-notes/troyraen/cloudbuild.md
@@ -1,8 +1,10 @@
-# Cloud Build
+# docs/source/working-notes/troyraen/cloudbuild.md
+
+## Cloud Build
 
 - [Overview of Cloud Build](https://cloud.google.com/build/docs/overview)
 - [Build configuration file schema](https://cloud.google.com/build/docs/build-config-file-schema)
-    - [Substituting variable values](https://cloud.google.com/build/docs/configuring-builds/substitute-variable-values) 
+    - [Substituting variable values](https://cloud.google.com/build/docs/configuring-builds/substitute-variable-values)
 
 Example Build config (yaml) file structure:
 
diff --git a/docs/source/working-notes/troyraen/elasticc/README.md b/docs/source/working-notes/troyraen/elasticc/README.md
index 03973066..1c1c4637 100644
--- a/docs/source/working-notes/troyraen/elasticc/README.md
+++ b/docs/source/working-notes/troyraen/elasticc/README.md
@@ -1,6 +1,8 @@
-# ELAsTiCC Challenge
+# docs/source/working-notes/troyraen/elasticc/README.md
 
-## Alert Format
+## ELAsTiCC Challenge
+
+### Alert Format
 
 Reference links:
 
diff --git a/docs/source/working-notes/troyraen/gcloud-examples.md b/docs/source/working-notes/troyraen/gcloud-examples.md
index 16c4e523..20751cc1 100644
--- a/docs/source/working-notes/troyraen/gcloud-examples.md
+++ b/docs/source/working-notes/troyraen/gcloud-examples.md
@@ -1,4 +1,6 @@
-# gcloud Examples<a name="gcloud-examples"></a>
+# docs/source/working-notes/troyraen/gcloud-examples.md
+
+## gcloud Examples<a name="gcloud-examples"></a>
 
 <!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 -->
 
@@ -19,7 +21,7 @@ External reference:
 
 - [Google's `gcloud` CLI reference](https://cloud.google.com/sdk/gcloud/reference)
 
-## Setup<a name="setup"></a>
+### Setup<a name="setup"></a>
 
 The following variables are used in many of the examples on this page.
 Set them to your own preferences.
@@ -45,7 +47,7 @@ export CLOUDSDK_COMPUTE_REGION='us-central1'
 export CLOUDSDK_COMPUTE_ZONE='us-central1-a'
 ```
 
-## BigQuery<a name="bigquery"></a>
+### BigQuery<a name="bigquery"></a>
 
 Create a dataset
 
@@ -58,7 +60,7 @@ bq mk --dataset "${GOOGLE_CLOUD_PROJECT}:dataset_name" \
     --location="${REGION}"
 ```
 
-## Cloud Functions<a name="cloud-functions"></a>
+### Cloud Functions<a name="cloud-functions"></a>
 
 ```bash
 CF_name="my-cloud-function"     # choose a name for your Cloud Function
@@ -76,7 +78,7 @@ gcloud functions deploy "${CF_name}" \
 gcloud functions delete "${CF_name}"
 ```
 
-## Cloud Run<a name="cloud-run"></a>
+### Cloud Run<a name="cloud-run"></a>
 
 - [Instructions to create resources with pubsub trigger](https://cloud.google.com/run/docs/triggering/pubsub-push#command-line)
 
@@ -173,7 +175,7 @@ gcloud pubsub subscriptions create "$SUBSCRIPTION" \
     --ack-deadline="$ACK_DEADLINE"
 ```
 
-## Cloud Storage<a name="cloud-storage"></a>
+### Cloud Storage<a name="cloud-storage"></a>
 
 Download the avro file for a single alert:
 
@@ -185,9 +187,9 @@ local_dir="/<path>/<to>/<local>/<dir>"
 gsutil cp "gs://${bucket}/${filename}" ${local_dir}/.
 ```
 
-## Compute Engine<a name="compute-engine"></a>
+### Compute Engine<a name="compute-engine"></a>
 
-### Compute Engine Schedule<a name="compute-engine-schedule"></a>
+#### Compute Engine Schedule<a name="compute-engine-schedule"></a>
 
 Create a schedule (only needs to be done once)
 [unix-cron format](https://cloud.google.com/scheduler/docs/configuring/cron-job-schedules)
@@ -220,7 +222,7 @@ gcloud compute instances remove-resource-policies "${nconductVM}" \
     --resource-policies="${nconductVMsched}"
 ```
 
-## Pub/Sub<a name="pubsub"></a>
+### Pub/Sub<a name="pubsub"></a>
 
 - [https://cloud.google.com/sdk/gcloud/reference/pubsub](https://cloud.google.com/sdk/gcloud/reference/pubsub)
 
@@ -238,7 +240,7 @@ gcloud pubsub subscriptions create "$SUBSCRIPTION" \
     --topic-project="$TOPIC_PROJECT"
 ```
 
-## Service account<a name="service-account"></a>
+### Service account<a name="service-account"></a>
 
 See also [service-account.md](service-account.md).
 
diff --git a/docs/source/working-notes/troyraen/index.rst b/docs/source/working-notes/troyraen/index.rst
index 4a643ade..2e4943e1 100644
--- a/docs/source/working-notes/troyraen/index.rst
+++ b/docs/source/working-notes/troyraen/index.rst
@@ -1,6 +1,11 @@
 Troy Raen's Working Notes
 =============================
 
+.. warning::
+
+    There are additional code, image, and other files in these directories that are not visible
+    from the docs pages. For a complete view of directory contents look in the repo, not the docs.
+
 Most notes in this directory won't be of interest to anyone else.
 However, here are some that might be:
 
@@ -18,11 +23,16 @@ However, here are some that might be:
 
 And here's all of them:
 
+Directory Table of Contents
+----------------------------
+
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :glob:
    :caption: All Notes
 
    *
-   */README
-   pr-reviews/*
+   */*
+   */*/*
+   */*/*/*
+   */*/*/*/*
diff --git a/docs/source/working-notes/troyraen/ingest-ztf-archive/README.md b/docs/source/working-notes/troyraen/ingest-ztf-archive/README.md
index d3ed8d88..8b6859d5 100644
--- a/docs/source/working-notes/troyraen/ingest-ztf-archive/README.md
+++ b/docs/source/working-notes/troyraen/ingest-ztf-archive/README.md
@@ -1,4 +1,6 @@
-# Ingest ZTF Archive
+# docs/source/working-notes/troyraen/ingest-ztf-archive/README.md
+
+## Ingest ZTF Archive
 
 The [ZTF archive](https://ztf.uw.edu/alerts/public) was ingested into the "ztf_alerts_v*" buckets and tables in early 2023.
 The following files contain the working notes and code that were used:
@@ -12,7 +14,7 @@ A cleaned-up version of the code that can be used in the future is at:
 - [ingest_tarballs.py](ingest_tarballs.py)
 - [setup.sh](setup.sh)
 
-## Instructions
+### Instructions
 
 1. Setup a VM to use for the ingestion ([setup.sh](setup.sh))
 2. Setup other GCP resources like buckets and tables if needed ([setup.sh](setup.sh))
diff --git a/docs/source/working-notes/troyraen/metadata-tracking.md b/docs/source/working-notes/troyraen/metadata-tracking.md
index 76f9cc19..e0980628 100644
--- a/docs/source/working-notes/troyraen/metadata-tracking.md
+++ b/docs/source/working-notes/troyraen/metadata-tracking.md
@@ -1,11 +1,13 @@
-# Metadata Tracking System
+# docs/source/working-notes/troyraen/metadata-tracking.md
 
-## todo
+## Metadata Tracking System
+
+### todo
 
 - [ ]  candid should be stored as an int, but currently using string f"{message_id}_unknown" for `alerts` stream messages that can't be matched to a candid.
 
 
-## Testing pieces
+### Testing pieces
 
 ```bash
 export GCP_PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -30,7 +32,7 @@ main.attach_file_metadata(blob, alert, context)
 ```
 
 
-## Broker Testing Instance
+### Broker Testing Instance
 Create/delete a broker testing instance
 ```bash
 # get the code
diff --git a/docs/source/working-notes/troyraen/performance-figures/README.md b/docs/source/working-notes/troyraen/performance-figures/README.md
index b8526845..5bcccdc0 100644
--- a/docs/source/working-notes/troyraen/performance-figures/README.md
+++ b/docs/source/working-notes/troyraen/performance-figures/README.md
@@ -1,4 +1,6 @@
-# Performance Figures
+# docs/source/working-notes/troyraen/performance-figures/README.md
+
+## Performance Figures
 
 Using figures.py in this directory:
 
@@ -77,7 +79,7 @@ for c in cols:
 
 <img src="figures/SuperNNova-ztf-20210914.png" alt=""/>
 
-## figures_OG
+### figures_OG
 
 ```python
 import figures_OG as figs
@@ -119,7 +121,7 @@ mplot._plot_incoming_rate_hist(ax, bin_per=bin_per, compare_cols=compare_cols)
 plt.show(block=False)
 ```
 
-## JOIN tables
+### JOIN tables
 
 ```python
 metacols = [
diff --git a/docs/source/working-notes/troyraen/performance-figures/dissertation.md b/docs/source/working-notes/troyraen/performance-figures/dissertation.md
index 2d7ec0e9..6dd3e54c 100644
--- a/docs/source/working-notes/troyraen/performance-figures/dissertation.md
+++ b/docs/source/working-notes/troyraen/performance-figures/dissertation.md
@@ -1,4 +1,6 @@
-# Performance figures for disseration
+# docs/source/working-notes/troyraen/performance-figures/dissertation.md
+
+## Performance figures for disseration
 
 Setup
 
diff --git a/docs/source/working-notes/troyraen/performance-figures/dissertation/README.md/lsst-rates/README.md b/docs/source/working-notes/troyraen/performance-figures/dissertation/README.md/lsst-rates/README.md
index 497db014..7427d808 100644
--- a/docs/source/working-notes/troyraen/performance-figures/dissertation/README.md/lsst-rates/README.md
+++ b/docs/source/working-notes/troyraen/performance-figures/dissertation/README.md/lsst-rates/README.md
@@ -1,4 +1,6 @@
-# Pipeline Performance at approx. LSST rates - Sept 23, 2021
+# docs/source/working-notes/troyraen/performance-figures/dissertation/README.md/lsst-rates/README.md
+
+## Pipeline Performance at approx. LSST rates - Sept 23, 2021
 
 - [Overview](#overview)
 - [Incoming alert info](#incoming-alert-info)
@@ -6,7 +8,7 @@
 - [Cloud Function execution](#cloud-function-execution)
 - [Billing](#billing)
 
-## Overview
+### Overview
 
 On Sept 23, incoming alert rates were very high for the first ~10 minutes, close to expected LSST-scale.
 Here I (Troy) document some aspects of how the pipeline performed.
@@ -25,7 +27,7 @@ Takeaways:
 - The Cloud Functions that store to BigQuery (*BigQuery* and *SuperNNova*) experience a large number of timeouts (which then get retried) when the incoming rate is high. I assume we are hitting a rate limit for streaming inserts, but I haven't checked. Update 11/30/2021: This was probably due to the fact that we make a `get_table` request with every streaming insert, and there is a limit of 100 "API requests per second per user per method" (does not apply to streaming inserts). This relevant streaming insert limit is 1 GB per second per project, and this shouldn't have been more than about 23 MB/second. Can't check the logs anymore because they're only stored for 30 days in GCP by default, and we haven't changed the defaults or exported logs. ([BigQuery quotas](https://cloud.google.com/bigquery/quotas))
 - The combination of many simultaneous Cloud Function instances and their large execution times results in high costs (>6x normal ZTF).
 
-## Incoming alert info
+### Incoming alert info
 
 - `kafka_timestamp` gets applied at IPAC.
 - There is no timestamp applied at ZADS (to my knowledge). The best info about ZADS rates comes from their Grafana dashboard.
@@ -43,7 +45,7 @@ ZADS dashboard during the dump and shortly after.
 
 For reference. ZADS dashboard at the end of the dump (starting at 01:10) for the next few hours.
 
-## Component processing times
+### Component processing times
 
 __Takeaways:__
 
@@ -130,7 +132,7 @@ def plot_proct():
         plt.close(fig)
 ```
 
-## Cloud Function execution
+### Cloud Function execution
 
 Takeaways:
 
@@ -157,7 +159,7 @@ __Figures__
 
 *SuperNNova*
 
-## Billing
+### Billing
 
 Takeaways:
 
diff --git a/docs/source/working-notes/troyraen/performance-figures/figures/allwise/README.md b/docs/source/working-notes/troyraen/performance-figures/figures/allwise/README.md
index 749dd0e4..c2a524f5 100644
--- a/docs/source/working-notes/troyraen/performance-figures/figures/allwise/README.md
+++ b/docs/source/working-notes/troyraen/performance-figures/figures/allwise/README.md
@@ -1,4 +1,6 @@
-# AllWISE BigQuery cross match
+# docs/source/working-notes/troyraen/performance-figures/figures/allwise/README.md
+
+## AllWISE BigQuery cross match
 
 [billing#billing]()
 
@@ -58,7 +60,7 @@ def plot_proct():
 ```
 
 
-## Billing
+### Billing
 
 <img src="GCPbilling-bigquery-20210926.png" alt="GCPbilling-bigquery-20210926.png" width="800"/>
 
diff --git a/docs/source/working-notes/troyraen/performance-figures/figures/lsst-rates/README.md b/docs/source/working-notes/troyraen/performance-figures/figures/lsst-rates/README.md
index cec4c810..a1d22417 100644
--- a/docs/source/working-notes/troyraen/performance-figures/figures/lsst-rates/README.md
+++ b/docs/source/working-notes/troyraen/performance-figures/figures/lsst-rates/README.md
@@ -1,4 +1,6 @@
-# Pipeline Performance at approx. LSST rates - Sept 23, 2021
+# docs/source/working-notes/troyraen/performance-figures/figures/lsst-rates/README.md
+
+## Pipeline Performance at approx. LSST rates - Sept 23, 2021
 
 - [Overview](#overview)
 - [Incoming alert info](#incoming-alert-info)
@@ -6,7 +8,7 @@
 - [Cloud Function execution](#cloud-function-execution)
 - [Billing](#billing)
 
-## Overview
+### Overview
 
 On Sept 23, incoming alert rates were very high for the first \~10 minutes, close to expected LSST-scale.
 Here I (Troy) document some aspects of how the pipeline performed.
@@ -23,7 +25,7 @@ Takeaways:
 - The Cloud Functions that store to BigQuery (*BigQuery* and *SuperNNova*) experience a large number of timeouts (which then get retried) when the incoming rate is high. I assume we are hitting a rate limit for streaming inserts, but I haven't checked. Update 11/30/2021: This was probably due to the fact that we make a `get_table` request with every streaming insert, and there is a limit of 100 "API requests per second per user per method" (does not apply to streaming inserts). This relevant streaming insert limit is 1 GB per second per project, and this shouldn't have been more than about 23 MB/second. Can't check the logs anymore because they're only stored for 30 days in GCP by default, and we haven't changed the defaults or exported logs. ([BigQuery quotas](https://cloud.google.com/bigquery/quotas))
 - The combination of many simultaneous Cloud Function instances and their large execution times results in high costs (>6x normal ZTF).
 
-## Incoming alert info
+### Incoming alert info
 
 - `kafka_timestamp` gets applied at IPAC.
 - There is no timestamp applied at ZADS (to my knowledge). The best info about ZADS rates comes from their Grafana dashboard.
@@ -41,7 +43,7 @@ ZADS dashboard during the dump and shortly after.
 
 For reference. ZADS dashboard at the end of the dump (starting at 01:10) for the next few hours.
 
-## Component processing times
+### Component processing times
 
 __Takeaways:__
 - Our *consumer* can handle the average alert rate expected from LSST (\~17,000 alerts/min). It takes us \~8 minutes to get the ZTF alert backlog into the *alerts* stream. It's hard to tell how long it takes ZADS to dump these alerts, so I don't really know what our consumer's latency was relative to our actual incoming alert rate.
@@ -116,7 +118,7 @@ def plot_proct():
         plt.close(fig)
 ```
 
-## Cloud Function execution
+### Cloud Function execution
 
 Takeaways:
 - The execution time of an individual Cloud Function instance is higher when there are more simultaneous instances (i.e., incoming alert rate is higher). This seems strange to me. But it does explain the 10x billing increase (lots of instances with long execution times).
@@ -142,7 +144,7 @@ __Figures__
 
 *SuperNNova*
 
-## Billing
+### Billing
 
 Takeaways:
 - The combination of many simultaneous Cloud Function instances and their large execution times results in high costs (>6x normal ZTF).
diff --git a/docs/source/working-notes/troyraen/performance-figures/performance_figures.md b/docs/source/working-notes/troyraen/performance-figures/performance_figures.md
index fc841c89..d783d860 100644
--- a/docs/source/working-notes/troyraen/performance-figures/performance_figures.md
+++ b/docs/source/working-notes/troyraen/performance-figures/performance_figures.md
@@ -1,3 +1,5 @@
+# docs/source/working-notes/troyraen/performance-figures/performance_figures.md
+
 ## figures exploration
 
 1. query metadata table
diff --git a/docs/source/working-notes/troyraen/pr-reviews/djp-pep8.md b/docs/source/working-notes/troyraen/pr-reviews/djp-pep8.md
index 18f35148..62db76d2 100644
--- a/docs/source/working-notes/troyraen/pr-reviews/djp-pep8.md
+++ b/docs/source/working-notes/troyraen/pr-reviews/djp-pep8.md
@@ -1,3 +1,5 @@
+# docs/source/working-notes/troyraen/pr-reviews/djp-pep8.md
+
 ## djp-pep8: Summary
 
 The value_added Dataflow job fails because I have made a backwards incompatible change to `broker_utils`.
diff --git a/docs/source/working-notes/troyraen/pypi.md b/docs/source/working-notes/troyraen/pypi.md
index 88b9d4ac..a204aeaa 100644
--- a/docs/source/working-notes/troyraen/pypi.md
+++ b/docs/source/working-notes/troyraen/pypi.md
@@ -1,11 +1,13 @@
-# PyPI setup for pgb-utils
+# docs/source/working-notes/troyraen/pypi.md
+
+## PyPI setup for pgb-utils
 
 - [Packaging Python Projects](https://packaging.python.org/tutorials/packaging-projects/)
 - [Packaging and distributing projects](https://packaging.python.org/guides/distributing-packages-using-setuptools/)
 - [Example Project](https://github.com/pypa/sampleproject)
-- [Working in “development mode”](https://packaging.python.org/guides/distributing-packages-using-setuptools/#working-in-development-mode)  
+- [Working in “development mode”](https://packaging.python.org/guides/distributing-packages-using-setuptools/#working-in-development-mode)
 
-## Setup:
+### Setup:
 ```bash
 pgbenv
 python -m pip install --upgrade pip setuptools wheel
@@ -14,7 +16,7 @@ python -m pip install twine
 python3 -m pip install --upgrade build
 ```
 
-## Build the distribution and upload it to testpypi
+### Build the distribution and upload it to testpypi
 ```bash
 cd /Users/troyraen/Documents/PGB/repo/pgb_utils
 python3 -m build
@@ -23,7 +25,7 @@ python3 -m twine upload --repository testpypi dist/*
 View at: https://test.pypi.org/project/pgb-utils-alpha/0.0.1/
 
 
-## Build the distribution and upload it to PyPI
+### Build the distribution and upload it to PyPI
 ```bash
 cd /Users/troyraen/Documents/broker/repo2/pgb_utils
 python3 -m build
@@ -32,7 +34,7 @@ python3 -m twine upload dist/*
 View at: https://pypi.org/project/pgb-utils/0.1.0/
 
 
-## Work in development ("editable") mode:
+### Work in development ("editable") mode:
 ```bash
 conda create --name pgbutils python=3.7 pip ipython
 conda activate pgbutils
diff --git a/docs/source/working-notes/troyraen/python_fncs/README.md b/docs/source/working-notes/troyraen/python_fncs/README.md
index ef5f571e..eca79c0d 100644
--- a/docs/source/working-notes/troyraen/python_fncs/README.md
+++ b/docs/source/working-notes/troyraen/python_fncs/README.md
@@ -1,1 +1,5 @@
-# python_fncs: Useful Python functions
+# docs/source/working-notes/troyraen/python_fncs/README.md
+
+## python_fncs: Useful Python functions
+
+See the python modules under this directory.
diff --git a/docs/source/working-notes/troyraen/service-account.md b/docs/source/working-notes/troyraen/service-account.md
index 7420b33d..2e83083c 100644
--- a/docs/source/working-notes/troyraen/service-account.md
+++ b/docs/source/working-notes/troyraen/service-account.md
@@ -1,4 +1,6 @@
-# Service Accounts
+# docs/source/working-notes/troyraen/service-account.md
+
+## Service Accounts
 
 References:
 
@@ -12,7 +14,7 @@ References:
 - https://cloud.google.com/iam/docs/understanding-roles#predefined
 - https://cloud.google.com/sdk/gcloud/reference/resource-manager -->
 
-## Setup
+### Setup
 
 ```bash
 # Enter your own options:
@@ -30,7 +32,7 @@ ROLE="roles/viewer"
 SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com"
 ```
 
-## Create a service account, assign a role, and download a key file
+### Create a service account, assign a role, and download a key file
 
 If you are accessing a new project (or perhaps deactivated previous settings)
 you'll need to connect `gcloud` to the project via a
@@ -58,7 +60,7 @@ gcloud iam service-accounts keys create "$GOOGLE_APPLICATION_CREDENTIALS" \
     --iam-account="$SERVICE_ACCOUNT"
 ```
 
-## Switch the Service Account your API calls use
+### Switch the Service Account your API calls use
 
 This activates the service account for `gcloud` and `bq` calls:
 
diff --git a/docs/source/working-notes/troyraen/store-bigquery.md b/docs/source/working-notes/troyraen/store-bigquery.md
index e35b787f..fd894d8a 100644
--- a/docs/source/working-notes/troyraen/store-bigquery.md
+++ b/docs/source/working-notes/troyraen/store-bigquery.md
@@ -1,9 +1,11 @@
-# Cloud Function to load alerts to BigQuery tables
+# docs/source/working-notes/troyraen/store-bigquery.md
+
+## Cloud Function to load alerts to BigQuery tables
 
 Skip to [Test the end result](#test-the-end-result)
 
 
-## Test pieces of the cloud fnc
+### Test pieces of the cloud fnc
 
 ```bash
 export GCP_PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -24,7 +26,7 @@ alert_dict = troy.load_alert_file(kwargs)
 gcp_utils.insert_rows_bigquery(table_id, [alert_dict])
 ```
 
-## setup/run/stop/delete the testing instance
+### setup/run/stop/delete the testing instance
 
 Create/delete a broker testing instance
 ```bash
@@ -79,7 +81,7 @@ gcloud pubsub topics publish "$topic" --message="$cue"
 ```
 <!--
 
-## Test the end result
+### Test the end result
 
 ```python
 import os
diff --git a/docs/source/working-notes/troyraen/stream-looper/README.md b/docs/source/working-notes/troyraen/stream-looper/README.md
index 4235fd78..735db7bf 100644
--- a/docs/source/working-notes/troyraen/stream-looper/README.md
+++ b/docs/source/working-notes/troyraen/stream-looper/README.md
@@ -1,6 +1,8 @@
-# Streaming Stream Looper
+# docs/source/working-notes/troyraen/stream-looper/README.md
 
-## VM Setup
+## Streaming Stream Looper
+
+### VM Setup
 
 1. Define configs
 
@@ -74,7 +76,7 @@
        --machine-type "${vmtype}"
    ```
 
-## ZTF Stream
+### ZTF Stream
 
 Set a startup script to execute the python file in a background thread:
 
@@ -103,7 +105,7 @@ looper = StreamLooper(TOPIC_NAME, SUBSCRIPTION_NAME)
 looper.run_looper()
 ```
 
-## ELASTICC Stream
+### ELASTICC Stream
 
 Log in to the stream-looper VM and run the looper in a screen:
 
@@ -117,7 +119,7 @@ Log in to the stream-looper VM and run the looper in a screen:
 # bucketdir, workingdir
 ```
 
-### Incoming alerts
+#### Incoming alerts
 
 ```bash
 gcloud compute ssh "${vmname}"
@@ -140,7 +142,7 @@ project_id = "avid-heading-329016"
 StreamLooper(topic, subscrip, project_id).run_looper()
 ```
 
-### Outgoing classifications
+#### Outgoing classifications
 
 ```bash
 gcloud compute ssh "${vmname}"
diff --git a/docs/source/working-notes/troyraen/stream-looper/batch-stream-looper.md b/docs/source/working-notes/troyraen/stream-looper/batch-stream-looper.md
index da9424d0..4636482c 100644
--- a/docs/source/working-notes/troyraen/stream-looper/batch-stream-looper.md
+++ b/docs/source/working-notes/troyraen/stream-looper/batch-stream-looper.md
@@ -1,6 +1,8 @@
-# Setup stream-looper VM and topic
+# docs/source/working-notes/troyraen/stream-looper/batch-stream-looper.md
 
-## Create the Pub/Sub topic and allow public subscriptions
+## Setup stream-looper VM and topic
+
+### Create the Pub/Sub topic and allow public subscriptions
 
 ```bash
 PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -16,7 +18,7 @@ gcloud pubsub topics get-iam-policy $topic_path --format yaml > $fnametmp
 gcloud pubsub topics set-iam-policy $topic_path $fname
 ```
 
-## Create the VM and setup the consumer simulator
+### Create the VM and setup the consumer simulator
 
 ```bash
 vmname="stream-looper"
@@ -39,7 +41,7 @@ gcloud compute instances add-metadata "$vmname" --zone="$zone" --metadata=startu
 # gcloud compute ssh $vmname
 ```
 
-### Set a startup script to run consumer simulator indefinitely
+#### Set a startup script to run consumer simulator indefinitely
 
 Python script to trigger at startup.
 Save the following code to a root-executable file at
diff --git a/docs/source/working-notes/troyraen/v0.3.0/README.md b/docs/source/working-notes/troyraen/v0.3.0/README.md
index 76f31106..43b6fd6c 100644
--- a/docs/source/working-notes/troyraen/v0.3.0/README.md
+++ b/docs/source/working-notes/troyraen/v0.3.0/README.md
@@ -1,4 +1,6 @@
-# v0.3.0
+# docs/source/working-notes/troyraen/v0.3.0/README.md
+
+## v0.3.0
 
 - [`ZTF Stream` Dashboard](https://console.cloud.google.com/monitoring/dashboards/builder/090d10a0-f661-4768-831f-30c67dab50bf?project=ardent-cycling-243415&dashboardBuilderState=%257B%2522editModeEnabled%2522:false%257D&timeDomain=1w)
 
@@ -6,7 +8,7 @@
 - [Metrics, time series, and resources](https://cloud.google.com/monitoring/api/v3/metrics)
 - [Creating custom metrics](https://cloud.google.com/monitoring/custom-metrics/creating-metrics#monitoring_write_timeseries-python)
 
-## ToC
+### ToC
 
 - [Dec 22-24, 2020](#dec24)
 - [Dec 27, 2020](#dec27)
@@ -17,7 +19,7 @@
 ---
 
 <a name="dec24"></a>
-## Dec 22-24, 2020
+### Dec 22-24, 2020
 <!-- fs -->
 - Consumer: custom consumer, running on Compute Engine VM
     - kafka installed with:
@@ -75,7 +77,7 @@ Messages successfully published to PS topic `ztf_alert_data` (blue); failed mess
 <!-- fe Dec 24, 2020 -->
 
 <a name="dec27"></a>
-## Dec 27, 2020
+### Dec 27, 2020
 <!-- fs -->
 - [New] Consumer: Kafka -> PS Connector
     - started consumer when there were
@@ -117,7 +119,7 @@ Ingests the backlog in >20 min; seems to keep up with ZTF for the rest of the ni
 
 
 <a name="dec28"></a>
-## Dec 28, 2020
+### Dec 28, 2020
 <!-- fs -->
 - Consumer: Kafka -> PS Connector
 - GCS Avro storage: PS -> GCS Cloud Function
@@ -151,7 +153,7 @@ Max system lag is about 10 min.
 
 
 <a name="jan1"></a>
-## Jan 01, 2021
+### Jan 01, 2021
 <!-- fs -->
 Dataflow job looked fine (re-ingested at 10am) except for data freshness increased to almost 22 hrs.
 Stopping the job to start fresh for Jan 2.
@@ -188,7 +190,7 @@ ZTF dashboard for Jan 01, 2021.
 
 
 <a name="code"></a>
-## Code Snippets
+### Code Snippets
 <!-- fs -->
 __count the number of objects in the bucket matching day's topic__
 ```bash
diff --git a/docs/source/working-notes/troyraen/v0.3.1/README.md b/docs/source/working-notes/troyraen/v0.3.1/README.md
index 81054ec8..2569c298 100644
--- a/docs/source/working-notes/troyraen/v0.3.1/README.md
+++ b/docs/source/working-notes/troyraen/v0.3.1/README.md
@@ -1,3 +1,5 @@
-# v0.3.1:
+# docs/source/working-notes/troyraen/v0.3.1/README.md
 
-See [setup_test_v031.ipynb](setup_test_v031.ipynb) 
+## v0.3.1:
+
+See [setup_test_v031.ipynb](setup_test_v031.ipynb)
diff --git a/docs/source/working-notes/troyraen/v0.4.0/README.md b/docs/source/working-notes/troyraen/v0.4.0/README.md
index 3804ac0c..e4db2bb4 100644
--- a/docs/source/working-notes/troyraen/v0.4.0/README.md
+++ b/docs/source/working-notes/troyraen/v0.4.0/README.md
@@ -1,12 +1,14 @@
-# v0.4.0
+# docs/source/working-notes/troyraen/v0.4.0/README.md
+
+## v0.4.0
 
 - [Documentation of Changes](#documentation-of-changes)
 - [Test the Changes](#test-the-changes)
-- [Results Summary](#results-summary)  
+- [Results Summary](#results-summary)
 
 ---
 
-## Documentation of Changes
+### Documentation of Changes
 
 - PR [#60](https://github.com/mwvgroup/Pitt-Google-Broker/pull/60)
 - [rename-resources.md](rename-resources.md): accommodate generic survey
@@ -16,7 +18,7 @@
 
 ---
 
-## Test the Changes
+### Test the Changes
 
 __Dashboards__ (linked to specific times of tests below):
 - [ZTF: Consumer test](https://console.cloud.google.com/monitoring/dashboards/builder/broker-instance-ztf-v040?project=ardent-cycling-243415&dashboardBuilderState=%257B%2522editModeEnabled%2522:false%257D&startTime=20210509T171043-04:00&endTime=20210509T171543-04:00) (old topic, alerts flood in)
@@ -103,7 +105,7 @@ teardown="True"
 
 ---
 
-## Results Summary
+### Results Summary
 
 ZTF broker seems to run like normal, no more or different bugs/errors than normal.
 
diff --git a/docs/source/working-notes/troyraen/v0.4.0/pypi.md b/docs/source/working-notes/troyraen/v0.4.0/pypi.md
index 9ea93538..5843c00b 100644
--- a/docs/source/working-notes/troyraen/v0.4.0/pypi.md
+++ b/docs/source/working-notes/troyraen/v0.4.0/pypi.md
@@ -1,11 +1,13 @@
-# PyPI setup for pgb-utils
+# docs/source/working-notes/troyraen/v0.4.0/pypi.md
+
+## PyPI setup for pgb-utils
 
 - [Packaging Python Projects](https://packaging.python.org/tutorials/packaging-projects/)
 - [Packaging and distributing projects](https://packaging.python.org/guides/distributing-packages-using-setuptools/)
 - [Example Project](https://github.com/pypa/sampleproject)
-- [Working in “development mode”](https://packaging.python.org/guides/distributing-packages-using-setuptools/#working-in-development-mode)  
+- [Working in “development mode”](https://packaging.python.org/guides/distributing-packages-using-setuptools/#working-in-development-mode)
 
-## Setup:
+### Setup:
 ```bash
 pgbenv
 python -m pip install --upgrade pip setuptools wheel
@@ -14,7 +16,7 @@ python -m pip install twine
 python3 -m pip install --upgrade build
 ```
 
-## Build the distribution and upload it to testpypi
+### Build the distribution and upload it to testpypi
 ```bash
 cd /Users/troyraen/Documents/PGB/repotest/broker/broker_utils
 python3 -m build
@@ -25,7 +27,7 @@ View at: https://test.pypi.org/project/pgb-broker-utils
 
 Install with: `python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps pgb_broker_utils`
 
-## Build the distribution and upload it to PyPI
+### Build the distribution and upload it to PyPI
 ```bash
 cd /Users/troyraen/Documents/PGB/repo3/broker/broker_utils
 python3 -m build
@@ -34,7 +36,7 @@ python3 -m twine upload dist/*
 View at: https://pypi.org/project/pgb-broker-utils
 
 
-## Work in development ("editable") mode:
+### Work in development ("editable") mode:
 ```bash
 conda env remove --name brokerutils
 conda create --name brokerutils python=3.7 pip ipython
diff --git a/docs/source/working-notes/troyraen/v0.4.0/rename-resources.md b/docs/source/working-notes/troyraen/v0.4.0/rename-resources.md
index f26ed29b..59900ffd 100644
--- a/docs/source/working-notes/troyraen/v0.4.0/rename-resources.md
+++ b/docs/source/working-notes/troyraen/v0.4.0/rename-resources.md
@@ -1,4 +1,6 @@
-# Rename resources
+# docs/source/working-notes/troyraen/v0.4.0/rename-resources.md
+
+## Rename resources
 
 __Table of Contents__
 - [Names](#names)
@@ -7,7 +9,7 @@ __Table of Contents__
 
 ---
 
-## Names
+### Names
 <!-- fs -->
 The following resources were renamed to prepend an arbitrary survey name (note there can also be a testid appended to all names, but it is not shown here). The survey name is defined as a keyword when setting up the broker instance.
 
@@ -42,7 +44,7 @@ The following resources were renamed to prepend an arbitrary survey name (note t
 <!-- fe -->
 ---
 
-## Test the changes
+### Test the changes
 <!-- fs -->
 Dashboard snapshots:
 - [Live](https://console.cloud.google.com/monitoring/dashboards/builder/broker-instance-ztf-testsurveyname)
@@ -142,7 +144,7 @@ teardown="True"
 <!-- fe Test the changes -->
 ---
 
-## Update ZTF production broker
+### Update ZTF production broker
 <!-- fs -->
 These changes will happen seamlessly when this branch is merged to master and the broker is fully redeployed.
 However, the buckets for `alert_avros` and `sncosmo` already have data in them, so let's move it to buckets with the new names and update the relevant parts of the production broker.
diff --git a/docs/source/working-notes/troyraen/v0.4.0/schemas.md b/docs/source/working-notes/troyraen/v0.4.0/schemas.md
index e11109e6..ff1e7864 100644
--- a/docs/source/working-notes/troyraen/v0.4.0/schemas.md
+++ b/docs/source/working-notes/troyraen/v0.4.0/schemas.md
@@ -1,4 +1,6 @@
-# Schemas
+# docs/source/working-notes/troyraen/v0.4.0/schemas.md
+
+## Schemas
 
 Table of Contents:
 - [Create Schema Maps for `broker_utils`](#create-schema-maps-for-broker_utils)
@@ -8,7 +10,7 @@ Table of Contents:
 
 ---
 
-## Create Schema Maps for `broker_utils`
+### Create Schema Maps for `broker_utils`
 <!-- fs -->
 ```python
 from google.cloud import storage
@@ -83,7 +85,7 @@ for fname in [fztf, fdecat]:
 <!-- fe # Schema Maps -->
 ---
 
-## BigQuery schema json
+### BigQuery schema json
 <!-- fs -->
 We need a:
 - list of dictionaries, each with keys:
@@ -127,7 +129,7 @@ bq rm --table "${projectid}:${dataset}.salt2"
 <!-- fe BigQuery schema json -->
 ---
 
-## Test the changes
+### Test the changes
 <!-- fs -->
 Dashboard snapshots:
 - [DECAT Live](https://console.cloud.google.com/monitoring/dashboards/builder/broker-instance-decat-testschema)
@@ -226,7 +228,7 @@ teardown="True"
 <!-- fe Test the changes -->
 ---
 
-## Download and look at an Avro
+### Download and look at an Avro
 <!-- fs -->
 (Requires that we have already ingested an alert to the `alert_avros` bucket.)
 
diff --git a/docs/source/working-notes/troyraen/v0.5.0/README.md b/docs/source/working-notes/troyraen/v0.5.0/README.md
index e1d36877..5af16a9c 100644
--- a/docs/source/working-notes/troyraen/v0.5.0/README.md
+++ b/docs/source/working-notes/troyraen/v0.5.0/README.md
@@ -1,12 +1,14 @@
-# v0.5.0
+# docs/source/working-notes/troyraen/v0.5.0/README.md
 
-- [Results Summary](#results-summary)  
+## v0.5.0
+
+- [Results Summary](#results-summary)
 - [Documentation of Changes](#documentation-of-changes)
 - [Test the Changes](#test-the-changes)
 
 ---
 
-## Results Summary
+### Results Summary
 
 Auto-scheduler and cue-response checker appear to be working smoothly.
 
@@ -14,7 +16,7 @@ Documentation is back up on ReadTheDocs.
 
 ---
 
-## Documentation of Changes
+### Documentation of Changes
 
 - PR [#62](https://github.com/mwvgroup/Pitt-Google-Broker/pull/62)
 - Auto-scheduler: [schedule-night-conductor.md](schedule-night-conductor.md)
@@ -27,13 +29,13 @@ Started but didn't finish; TODO in a future version (this is v0.7.0):
 
 ---
 
-## Test the Changes
+### Test the Changes
 
 - [Create/delete a broker instance](#createdelete-a-broker-instance)
 - [Test the broker](#test-the-broker)
 
 <!-- fs -->
-### Create/delete a broker instance
+#### Create/delete a broker instance
 
  Create instance
 ```bash
@@ -72,10 +74,10 @@ sudo mv ~/pitt-reader.user.keytab ${consumerDir}/.
 ```
 
 
-### Test the broker
+#### Test the broker
 
 
-#### Test the auto-scheduler
+##### Test the auto-scheduler
 
 Schedule the broker to ingest a live topic for a few minutes and then shutdown.
 
diff --git a/docs/source/working-notes/troyraen/v0.5.0/external-connection.md b/docs/source/working-notes/troyraen/v0.5.0/external-connection.md
index b9637746..7d1b8566 100644
--- a/docs/source/working-notes/troyraen/v0.5.0/external-connection.md
+++ b/docs/source/working-notes/troyraen/v0.5.0/external-connection.md
@@ -1,9 +1,11 @@
-# external-connection
+# docs/source/working-notes/troyraen/v0.5.0/external-connection.md
+
+## external-connection
 
 Goal: Try to listen to and process one of our Pub/Sub streams as an outside user.
 
 
-## GCP and local setup for external account
+### GCP and local setup for external account
 <!-- fs -->
 Following [initial-setup.md](initial-setup.md)
 ```bash
@@ -49,7 +51,7 @@ python -m pip install -e .
 
 <!-- fe GCP and local setup -->
 
-## Setup IAM permissions on the Pub/Sub topic
+### Setup IAM permissions on the Pub/Sub topic
 <!-- fs -->
 Allow any GCP user to attach a subscription to our topic.
 - https://cloud.google.com/pubsub/docs/access-control#setting_a_policy
@@ -76,7 +78,7 @@ gcloud pubsub topics set-iam-policy $topic_path $fname
 
 <!-- fe IAM permissions -->
 
-## Create subscription and pull
+### Create subscription and pull
 <!-- fs -->
 __Command line:__
 - [Quickstart using the gcloud command-line tool](https://cloud.google.com/pubsub/docs/quickstart-cli)
@@ -119,6 +121,6 @@ smsg = pgbps.pull(subscription, project_id=my_project)  # EXECUTE FROM EXTERNAL
 ```
 <!-- fe subscription -->
 
-## Setup stream-looper VM and topic
+### Setup stream-looper VM and topic
 
 see [stream-looper.md](stream-looper.md)
diff --git a/docs/source/working-notes/troyraen/v0.5.0/schedule-night-conductor.md b/docs/source/working-notes/troyraen/v0.5.0/schedule-night-conductor.md
index a0455ed0..df35c3c8 100644
--- a/docs/source/working-notes/troyraen/v0.5.0/schedule-night-conductor.md
+++ b/docs/source/working-notes/troyraen/v0.5.0/schedule-night-conductor.md
@@ -1,4 +1,6 @@
-# Schedule Night Conductor
+# docs/source/working-notes/troyraen/v0.5.0/schedule-night-conductor.md
+
+## Schedule Night Conductor
 
 Cloud Scheduler cron job -> Pub/Sub -> Cloud Function -> start VM
 
diff --git a/docs/source/working-notes/troyraen/v0.5.0/stream-looper.md b/docs/source/working-notes/troyraen/v0.5.0/stream-looper.md
index da9424d0..cc96b988 100644
--- a/docs/source/working-notes/troyraen/v0.5.0/stream-looper.md
+++ b/docs/source/working-notes/troyraen/v0.5.0/stream-looper.md
@@ -1,6 +1,8 @@
-# Setup stream-looper VM and topic
+# docs/source/working-notes/troyraen/v0.5.0/stream-looper.md
 
-## Create the Pub/Sub topic and allow public subscriptions
+## Setup stream-looper VM and topic
+
+### Create the Pub/Sub topic and allow public subscriptions
 
 ```bash
 PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -16,7 +18,7 @@ gcloud pubsub topics get-iam-policy $topic_path --format yaml > $fnametmp
 gcloud pubsub topics set-iam-policy $topic_path $fname
 ```
 
-## Create the VM and setup the consumer simulator
+### Create the VM and setup the consumer simulator
 
 ```bash
 vmname="stream-looper"
@@ -39,7 +41,7 @@ gcloud compute instances add-metadata "$vmname" --zone="$zone" --metadata=startu
 # gcloud compute ssh $vmname
 ```
 
-### Set a startup script to run consumer simulator indefinitely
+#### Set a startup script to run consumer simulator indefinitely
 
 Python script to trigger at startup.
 Save the following code to a root-executable file at
diff --git a/docs/source/working-notes/troyraen/v0.6.0/README.md b/docs/source/working-notes/troyraen/v0.6.0/README.md
index 993e8dd6..cee30c07 100644
--- a/docs/source/working-notes/troyraen/v0.6.0/README.md
+++ b/docs/source/working-notes/troyraen/v0.6.0/README.md
@@ -1,7 +1,9 @@
-# v0.6.0
+# docs/source/working-notes/troyraen/v0.6.0/README.md
+
+## v0.6.0
 
 See:
 
 - [Test Pub/Sub tutorial from external account](test-pubsub-pricing.md)
 - [Test stream-looper](test-stream-looper.md)
-- [Update the ZTF production broker to current](update-production.md)  
+- [Update the ZTF production broker to current](update-production.md)
diff --git a/docs/source/working-notes/troyraen/v0.6.0/update-production.md b/docs/source/working-notes/troyraen/v0.6.0/update-production.md
index fb93d760..8caec443 100644
--- a/docs/source/working-notes/troyraen/v0.6.0/update-production.md
+++ b/docs/source/working-notes/troyraen/v0.6.0/update-production.md
@@ -1,4 +1,6 @@
-# Update the ZTF production broker to current
+# docs/source/working-notes/troyraen/v0.6.0/update-production.md
+
+## Update the ZTF production broker to current
 
 Functionality of current production broker should be the same as current repo code,
 but some of the resource names (e.g., pubsub) have not yet been updated to the new syntax rules.
@@ -14,7 +16,7 @@ Doing that now.
     - [x]  bigquery (dataset and table names do not change), check that alerts made it into each table.
     - [x]  cloud function ps_to_gcs will be updated with a new name and to use broker_utils
 
-## run setup_broker.sh
+### run setup_broker.sh
 
 Run the setup script:
 ```bash
@@ -43,7 +45,7 @@ broker_bucket="${PROJECT_ID}-${survey}-broker_files"
 ./create_vms.sh "$broker_bucket" "$testid" "$teardown" "$survey" 2>&1 | tee $fout
 ```
 
-## push some alerts through
+### push some alerts through
 
 Start the broker without the consumer
 ```bash
@@ -75,7 +77,7 @@ cue=END
 gcloud pubsub topics publish "$topic" --message="$cue"
 ```
 
-## pull the alerts and make sure they are as expected
+### pull the alerts and make sure they are as expected
 
 ```python
 from google.cloud import storage
diff --git a/docs/source/working-notes/troyraen/v0.6.2/README.md b/docs/source/working-notes/troyraen/v0.6.2/README.md
index c16f55ba..22822fb4 100644
--- a/docs/source/working-notes/troyraen/v0.6.2/README.md
+++ b/docs/source/working-notes/troyraen/v0.6.2/README.md
@@ -1,4 +1,6 @@
-# v0.6.2: Issue \#68
+# docs/source/working-notes/troyraen/v0.6.2/README.md
+
+## v0.6.2: Issue \#68
 
 [\#68](https://github.com/mwvgroup/Pitt-Google-Broker/issues/68)
 
diff --git a/docs/source/working-notes/troyraen/v0.7.0/README.md b/docs/source/working-notes/troyraen/v0.7.0/README.md
index 644f6098..f52706ab 100644
--- a/docs/source/working-notes/troyraen/v0.7.0/README.md
+++ b/docs/source/working-notes/troyraen/v0.7.0/README.md
@@ -1,4 +1,6 @@
-# v0.7.0
+# docs/source/working-notes/troyraen/v0.7.0/README.md
+
+## v0.7.0
 
 -   Implements SuperNNova as a Cloud Function.
 -   Adds the extragalactic transients filter as a Cloud Function, emitting the Pub/Sub stream that SuperNNova listens to.
@@ -11,7 +13,7 @@ Working notes:
 -   [supernnova_train_a_model.md](https://github.com/mwvgroup/Pitt-Google-Broker/tree/troy/troy/SNN/supernnova_train_a_model.md)
 (not necessary for this PR, but good for future reference)
 
-## Test the changes
+### Test the changes
 
 Note: The best place to see that/how well this is working is the ZTF *production*
 instance, not the testing instance created below.
@@ -30,7 +32,7 @@ See:
 -   BigQuery table
     -   [ztf_alerts.SuperNNova](https://console.cloud.google.com/bigquery?project=ardent-cycling-243415&d=ztf_alerts&p=ardent-cycling-243415&t=SuperNNova&page=table&ws=!1m5!1m4!4m3!1sardent-cycling-243415!2sztf_alerts!3sSuperNNova)
 
-### Code used to create and run the broker testing instance
+#### Code used to create and run the broker testing instance
 
 Create/delete a broker testing instance
 ```bash
diff --git a/docs/source/working-notes/troyraen/v0.7.0/supernnova.md b/docs/source/working-notes/troyraen/v0.7.0/supernnova.md
index a7704462..a7b1d3a2 100644
--- a/docs/source/working-notes/troyraen/v0.7.0/supernnova.md
+++ b/docs/source/working-notes/troyraen/v0.7.0/supernnova.md
@@ -1,14 +1,16 @@
-# Implementing SuperNNova Classifier
+# docs/source/working-notes/troyraen/v0.7.0/supernnova.md
+
+## Implementing SuperNNova Classifier
 
 SuperNNova Links:
 - [docs](https://supernnova.readthedocs.io/en/latest/index.html)
 - [github](https://github.com/supernnova/SuperNNova)
-- [arXiv paper](https://arxiv.org/pdf/1901.06384.pdf)  
+- [arXiv paper](https://arxiv.org/pdf/1901.06384.pdf)
 
 The following is mostly code to develop and test and Cloud Function.
 This uses a pre-trained model provided by the SuperNNova team.
 
-## Preliminary exploration
+### Preliminary exploration
 
 Following [run_onthefly.py](https://github.com/supernnova/SuperNNova/blob/master/run_onthefly.py)
 
@@ -92,7 +94,7 @@ def reformat_to_df(pred_probs, ids=None):
 ```
 
 
-## Test the Cloud Function pieces locally
+### Test the Cloud Function pieces locally
 
 ```bash
 export GCP_PROJECT=$GOOGLE_CLOUD_PROJECT
@@ -118,7 +120,7 @@ snn_msg = gcp_utils.pull_pubsub('test')[0]
 gcp_utils.insert_rows_bigquery(bq_table, [snn_dict])
 ```
 
-### Classify known Ia
+#### Classify known Ia
 
 The docs indicate that "usually" class0 indicates a Ia and class1 indicates non-Ia,
 but this will depend on how the model was trained.
@@ -150,7 +152,7 @@ snn_dict
  'pred_class': 1}
 ```
 
-## Local, full test
+### Local, full test
 
 ```bash
 conda create -n snn python=3.7
@@ -205,7 +207,7 @@ for r, row in enumerate(snn_queryjob):
 ```
 This works.
 
-## Deploy Cloud Function
+### Deploy Cloud Function
 
 ```bash
 survey="ztf"
@@ -221,9 +223,13 @@ gcloud functions deploy "$classify_snn_CF_name" \
     --trigger-topic "$classify_snn_trigger_topic" \
     --set-env-vars TESTID="$testid",SURVEY="$survey"
 ```
+
 This errors out with:
-```ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Build failed: Build error details not available.Please check the logs at https://console.cloud.google.com/cloud-build/builds;region=us-central1/d782dfbb-285d-44aa-a164-040e48660089?project=591409139500. Please visit https://cloud.google.com/functions/docs/troubleshooting#build for in-depth troubleshooting documentation for build related errors.
+
 ```
+ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Build failed: Build error details not available.Please check the logs at https://console.cloud.google.com/cloud-build/builds;region=us-central1/d782dfbb-285d-44aa-a164-040e48660089?project=591409139500. Please visit https://cloud.google.com/functions/docs/troubleshooting#build for in-depth troubleshooting documentation for build related errors.
+```
+
 I cannot find any more specific info in the logs or at the provided links.
 The step that it fails on is called "uploading_python_pkg_layer".
 
diff --git a/docs/source/working-notes/troyraen/v0.7.0/supernnova_train_a_model.md b/docs/source/working-notes/troyraen/v0.7.0/supernnova_train_a_model.md
index 5ca21902..52c32515 100644
--- a/docs/source/working-notes/troyraen/v0.7.0/supernnova_train_a_model.md
+++ b/docs/source/working-notes/troyraen/v0.7.0/supernnova_train_a_model.md
@@ -1,4 +1,6 @@
-# Train a SuperNNova Model
+# docs/source/working-notes/troyraen/v0.7.0/supernnova_train_a_model.md
+
+## Train a SuperNNova Model
 
 Links
 - [github.com/supernnova/SuperNNova](https://github.com/supernnova/SuperNNova)
@@ -13,7 +15,7 @@ Links
     - random forest from salt2 fits
     - bayesian RNN
 
-## setup
+### setup
 folowing the two quickstarts in readthedocs:
 ```bash
 gcloud compute instances start troy
@@ -34,7 +36,7 @@ pip install supernnova
 ipython
 ```
 
-## train and validate a model using the test set
+### train and validate a model using the test set
 ```bash
 gcloud compute instances start troy
 gcloud compute ssh troy
diff --git a/docs/source/working-notes/troyraen/v0.7.0/track_performance.md b/docs/source/working-notes/troyraen/v0.7.0/track_performance.md
index efc136ef..c23db864 100644
--- a/docs/source/working-notes/troyraen/v0.7.0/track_performance.md
+++ b/docs/source/working-notes/troyraen/v0.7.0/track_performance.md
@@ -1,3 +1,5 @@
+# docs/source/working-notes/troyraen/v0.7.0/track_performance.md
+
 ## Make the BigQuery table
 
 ```bash
diff --git a/docs/source/working-notes/troyraen/v0.7.1/README.md b/docs/source/working-notes/troyraen/v0.7.1/README.md
index 980d86c3..7add8628 100644
--- a/docs/source/working-notes/troyraen/v0.7.1/README.md
+++ b/docs/source/working-notes/troyraen/v0.7.1/README.md
@@ -1,4 +1,6 @@
-# v0.7.1
+# docs/source/working-notes/troyraen/v0.7.1/README.md
+
+## v0.7.1
 
 Starts a system to track metadata for provenance and performance benchmarking.
 - Adds custom metadata attributes to messages in all Pub/Sub streams, except "alerts".
@@ -11,14 +13,14 @@ See [PR \#72](https://github.com/mwvgroup/Pitt-Google-Broker/pull/72)
 Working notes:
 - [process_streams.md](process_streams.md) (setup/test the processing script)
 
-## Test the changes
+### Test the changes
 
 For the results of the tests, see:
 - [logs: process-pubsub-counters](https://console.cloud.google.com/logs/query;query=logName%3D%22projects%2Fardent-cycling-243415%2Flogs%2Fprocess-pubsub-counters%22;timeRange=P7D;cursorTimestamp=2021-08-23T03:06:56.058162537Z?project=ardent-cycling-243415)
 - [BigQuery metadata table](https://console.cloud.google.com/bigquery?project=ardent-cycling-243415&d=ztf_alerts_v071&p=ardent-cycling-243415&t=metadata&page=table&ws=!1m5!1m4!4m3!1sardent-cycling-243415!2sztf_alerts_v071!3smetadata)
 
 
-### Code used to create and run the broker testing instance
+#### Code used to create and run the broker testing instance
 
 Create/delete a broker testing instance
 ```bash
diff --git a/docs/source/working-notes/troyraen/v0.7.1/process_streams.md b/docs/source/working-notes/troyraen/v0.7.1/process_streams.md
index 76250e81..b7a91e02 100644
--- a/docs/source/working-notes/troyraen/v0.7.1/process_streams.md
+++ b/docs/source/working-notes/troyraen/v0.7.1/process_streams.md
@@ -1,9 +1,11 @@
-# Create and test process_pubsub_counters.py
+# docs/source/working-notes/troyraen/v0.7.1/process_streams.md
+
+## Create and test process_pubsub_counters.py
 
 - [broker/night_conductor/end_night/process_pubsub_counters.py](../../../broker/night_conductor/end_night/process_pubsub_counters.py)
 
 
-## Make the BigQuery table
+### Make the BigQuery table
 
 ```bash
 cd /Users/troyraen/Documents/broker/repo3/broker/setup_broker
@@ -15,7 +17,7 @@ bq mk --table ${PROJECT_ID}:${dataset}.${table} templates/bq_${survey}_${table}_
 ```
 
 
-## Timestamps exploration
+### Timestamps exploration
 
 ```python
 import time
@@ -37,7 +39,7 @@ fseconds = float(f'{seconds}.{tmpnano}')
 dt = datetime.utcfromtimestamp(fseconds)
 ```
 
-## Test process_pubsub_counters.py on the SuperNNova cloud function
+### Test process_pubsub_counters.py on the SuperNNova cloud function
 
 ```bash
 cd /Users/troyraen/Documents/broker/repo3/broker/night_conductor/end_night/
@@ -79,7 +81,7 @@ gcp_utils.insert_rows_bigquery(collector.bq_table, collector.metadata_dicts_list
 # collector.collect_and_store_all_metadata()
 ```
 
-## Test process_pubsub_counters.py on the full pipeline
+### Test process_pubsub_counters.py on the full pipeline
 
 ```bash
 cd /Users/troyraen/Documents/broker/repo3/broker/night_conductor/end_night/
@@ -121,7 +123,7 @@ collector._join_metadata()  # collector.metadata_df
 collector._load_metadata_to_bigquery()
 ```
 
-## Process last night's ZTF stream
+### Process last night's ZTF stream
 
 In python:
 ```python
@@ -148,7 +150,7 @@ python3 process_pubsub_counters.py --survey=$survey --production --timeout=$t
 # python3 process_pubsub_counters.py --survey=$survey --production --batch_size=$b --single_batch=$sb
 ```
 
-### Streaming
+#### Streaming
 
 ```python
 import process_pubsub_counters as ppc
diff --git a/docs/source/working-notes/troyraen/ztf-v4.02/readme.md b/docs/source/working-notes/troyraen/ztf-v4.02/readme.md
index fb9fdb16..90e4c9fc 100644
--- a/docs/source/working-notes/troyraen/ztf-v4.02/readme.md
+++ b/docs/source/working-notes/troyraen/ztf-v4.02/readme.md
@@ -1,6 +1,8 @@
-# Update to ZTF Avro Schema v4.02
+# docs/source/working-notes/troyraen/ztf-v4.02/readme.md
 
-## Download the schema files
+## Update to ZTF Avro Schema v4.02
+
+### Download the schema files
 
 ```bash
 baseurl="https://raw.githubusercontent.com/ZwickyTransientFacility/ztf-avro-alert/master/schema/"
@@ -19,7 +21,7 @@ for schema in ${schemas[@]}; do
 done
 ```
 
-## Load schema
+### Load schema
 
 ```python
 import fastavro
@@ -27,7 +29,7 @@ import fastavro
 schema = fastavro.schema.load_schema("schema/ztf.alert.alert.avsc")
 ```
 
-## Create the BigQuery schema file and then create the table
+### Create the BigQuery schema file and then create the table
 
 ```python
 import numpy as np
@@ -111,7 +113,7 @@ bq show --schema --format=prettyjson \
 bq mk --table ardent-cycling-243415:ztf.alerts_v4_02 ${schema_file}
 ```
 
-## Create the bucket
+### Create the bucket
 
 ```bash
 # copied from broker/cloud_functions/ps_to_gcs/deploy.sh
@@ -129,7 +131,7 @@ gcloud storage buckets add-iam-policy-binding "gs://${avro_bucket}" \
     --role="roles/storage.objectViewer"
 ```
 
-## Update VERSIONTAG for all cloud functions
+### Update VERSIONTAG for all cloud functions
 
 ```bash
 survey=ztf
diff --git a/setup.py b/setup.py
index 21e10aa7..039f1276 100644
--- a/setup.py
+++ b/setup.py
@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
 """Pitt-Google Broker.
-Example setup.py: https://github.com/pypa/sampleproject/blob/main/setup.py
 
-This file is required for Read the Docs.
+* ---- This file is required for Read the Docs. ---- *
+
+Example setup.py: https://github.com/pypa/sampleproject/blob/main/setup.py
 
 The Pitt-Google Broker package is free software: you can redistribute it and/or
 modify it under the terms of the GNU General Public License as published


Test patch:
diff --git a/broker/broker_utils/broker_utils/testing.py b/broker/broker_utils/broker_utils/testing.py
index 810d9ffd..74d416cf 100644
--- a/broker/broker_utils/broker_utils/testing.py
+++ b/broker/broker_utils/broker_utils/testing.py
@@ -31,9 +31,9 @@ def __init__(self, alert_dir: Union[str, Path] = "ztf"):
                 Either the path to a directory containing alerts or one of the
                 following strings.
                 "ALERT_DIR" or "alert_dir": The path will be obtained from the
-                    environment variable ALERT_DIR.
+                environment variable ALERT_DIR.
                 "ztf" or "elasticc": The path will be obtained from the environment
-                    variable given by ``f"ALERT_DIR_{alert_dir.upper()}"``
+                variable given by ``f"ALERT_DIR_{alert_dir.upper()}"``
         """
         if alert_dir in ["ALERT_DIR", "alert_dir"]:
             self.alert_dir = Path(os.getenv("ALERT_DIR"))
diff --git a/docs/source/working-notes/troyraen/AbrilCVs/deploy_to_user_test_project.md b/docs/source/working-notes/troyraen/AbrilCVs/deploy_to_user_test_project.md
index 18dc8e26..c4bdc41a 100644
--- a/docs/source/working-notes/troyraen/AbrilCVs/deploy_to_user_test_project.md
+++ b/docs/source/working-notes/troyraen/AbrilCVs/deploy_to_user_test_project.md
@@ -1,4 +1,6 @@
-# Deploy Abril CVs cross match to GCP project `pitt-google-broker-user-test`
+# docs/source/working-notes/troyraen/AbrilCVs/deploy_to_user_test_project.md
+
+## Deploy Abril CVs cross match to GCP project `pitt-google-broker-user-test`
 
 ```bash
 export GOOGLE_CLOUD_PROJECT="avid-heading-329016"
diff --git a/docs/source/working-notes/troyraen/Rubin-stream-test/README.md b/docs/source/working-notes/troyraen/Rubin-stream-test/README.md
index 5d844238..9af182eb 100644
--- a/docs/source/working-notes/troyraen/Rubin-stream-test/README.md
+++ b/docs/source/working-notes/troyraen/Rubin-stream-test/README.md
@@ -1,4 +1,6 @@
-# Connect Pitt-Google to the Rubin alert stream testing deployment
+# docs/source/working-notes/troyraen/Rubin-stream-test/README.md
+
+## Connect Pitt-Google to the Rubin alert stream testing deployment
 
 Note: The active copy of this README.md is in broker/consumer/rubin and will be kept up to date as the main LSST alert stream developments. This README.md here is specifically for this test stream.
 
@@ -22,7 +24,7 @@ For other methods, see [Alternative methods for handling the schema](#alternativ
 
 Below is the code I used to set up the necessary resources in GCP, ingest the Rubin stream, pull messages from the resulting Pub/Sub stream and deserialize the alerts.
 
-# Setup
+## Setup
 
 Clone the repo, checkout the branch (currently `rubin`, but in the future will be merged into `master`), cd into the directory:
 
@@ -86,9 +88,9 @@ gcloud compute instances create "$consumerVM" \
     --tags="$firewallrule"
 ```
 
-# Ingest the Rubin test stream
+## Ingest the Rubin test stream
 
-## Setup
+### Setup
 
 ```bash
 # start the consumer vm and ssh in
@@ -102,9 +104,9 @@ workingdir="${brokerdir}/consumer/rubin"
 # at the very top of this README file.
 ```
 
-## Test the connection
+### Test the connection
 
-### Check available Kafka topics
+#### Check available Kafka topics
 
 ```bash
 /bin/kafka-topics \
@@ -114,7 +116,7 @@ workingdir="${brokerdir}/consumer/rubin"
 # should see output that includes the topic: alerts-simulated
 ```
 
-### Test the topic connection using the Kafka Console Consumer
+#### Test the topic connection using the Kafka Console Consumer
 
 Set Java env variable
 
@@ -147,7 +149,7 @@ sudo /bin/kafka-avro-console-consumer \
 # if successful, you will see a lot of JSON flood the terminal
 ```
 
-## Run the Kafka -> Pub/Sub connector
+### Run the Kafka -> Pub/Sub connector
 
 Setup:
 
@@ -170,7 +172,7 @@ sudo sed -i "s/KAFKA_TOPIC/${KAFKA_TOPIC}/g" ${fconfig}
 Run the connector:
 
 ```bash
-mydir="/home/troyraen"  # use my dir because don't have permission to write to workingdir
+mydir="/home/troyraen"  ## use my dir because don't have permission to write to workingdir
 fout_run="${mydir}/run-connector.out"
 sudo /bin/connect-standalone \
     ${workingdir}/psconnect-worker.properties \
@@ -178,7 +180,7 @@ sudo /bin/connect-standalone \
     &> ${fout_run}
 ```
 
-# Pull a Pub/Sub message and open it
+## Pull a Pub/Sub message and open it
 
 In the future, we should download schemas from the Confluent Schema Registry and store them.
 Then for each alert, check the schema version in the Confluent Wire header, and load the schema file using `fastavro`.
@@ -231,9 +233,9 @@ for received_message in response.received_messages:
     print(f"alertId: {alertId}, diaSourceId: {diaSourceId}, psFlux: {psFlux}")
 ```
 
-# Alternative methods for handling the schema
+## Alternative methods for handling the schema
 
-## Download with a `GET` request, and read the alert's schema version from the Confluent Wire header
+### Download with a `GET` request, and read the alert's schema version from the Confluent Wire header
 
 In the future, we should download schemas from the Confluent Schema Registry and store them (assuming we do not use the schema registry directly in the Kafka connector).
 Then for each alert, check the schema version in the Confluent Wire header, and load the schema file using `fastavro`.
@@ -242,7 +244,7 @@ Pub/Sub topics can be configured with an Avro schema attached, but it cannot be
 We would have to create a new topic for every schema version.
 Therefore, I don't think we should do it this way.
 
-### Download a schema from the Confluent Schema Registry using a `GET` request
+#### Download a schema from the Confluent Schema Registry using a `GET` request
 
 ```bash
 SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO=$KAFKA_USERNAME:$KAFKA_PASSWORD
@@ -256,7 +258,7 @@ curl --silent -X GET -u $SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO $SCHEMA_REGISTRY_U
 curl --silent -X GET -u $SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO $SCHEMA_REGISTRY_URL/schemas/ids/${schema_version} > $fout_rubinschema
 ```
 
-### Read the alert's schema version from the Confluent Wire header
+#### Read the alert's schema version from the Confluent Wire header
 
 The following is copied from
 https://github.com/lsst-dm/alert_stream/blob/main/python/lsst/alert/stream/serialization.py
@@ -286,7 +288,7 @@ header_bytes = alert_bytes[:5]
 schema_version = deserialize_confluent_wire_header(header_bytes)
 ```
 
-## Use the Confluent Schema Registry with the Kafka Connector
+### Use the Confluent Schema Registry with the Kafka Connector
 
 Kafka Connect can use the Confluent Schema Registry directly.
 But schemas are stored under subjects and Kafka Connect is picky about how those
diff --git a/docs/source/working-notes/troyraen/alerts-for-testing/README.md b/docs/source/working-notes/troyraen/alerts-for-testing/README.md
index 63871d0b..a20bd477 100644
--- a/docs/source/working-notes/troyraen/alerts-for-testing/README.md
+++ b/docs/source/working-notes/troyraen/alerts-for-testing/README.md
@@ -1,11 +1,14 @@
-# alerts-for-testing: ZTF Alerts for Testing Purposes
+
+# docs/source/working-notes/troyraen/alerts-for-testing/README.md
+
+## alerts-for-testing: ZTF Alerts for Testing Purposes
 
 There are 50 ZTF alert avro files in this directory.
 Here we list the files and document the code originally used to find them and to upload them to a Cloud Storage bucket.
 
 For instructions on downloading and working with these alerts, see [alert-utils.md](alert-utils.md).
 
-## Overview of files in this directory
+### Overview of files in this directory
 
 ```python
 >>> fnames_pass_all  # these 37 pass all science filters, fitters, and classifiers
@@ -63,7 +66,7 @@ For instructions on downloading and working with these alerts, see [alert-utils.
  'ZTF18abbwsvo.1703210606215015045.ztf_20210831_programid1.avro']
 ```
 
-## Code used to retrieve the files
+### Code used to retrieve the files
 
 ```python
 from broker_utils import data_utils, gcp_utils
@@ -128,7 +131,7 @@ for f in fnames_pass_none:
     gcp_utils.cs_download_file(localdir, bucket_id, f)
 ```
 
-## Code used to upload the files to a testing bucket
+### Code used to upload the files to a testing bucket
 
 ```bash
 testing_bucket="${GOOGLE_CLOUD_PROJECT}-ztf-test_alerts"
diff --git a/docs/source/working-notes/troyraen/alerts-for-testing/alert-utils.md b/docs/source/working-notes/troyraen/alerts-for-testing/alert-utils.md
index c88fc3d3..dcc3fab8 100644
--- a/docs/source/working-notes/troyraen/alerts-for-testing/alert-utils.md
+++ b/docs/source/working-notes/troyraen/alerts-for-testing/alert-utils.md
@@ -1,4 +1,6 @@
-# Alert Utils
+# docs/source/working-notes/troyraen/alerts-for-testing/alert-utils.md
+
+## Alert Utils
 
 The live version of this document has been moved into the documentation ([Alerts for Testing](docs/source/broker/alerts-for-testing.rst)).
 We leave the original version below, for reference.
@@ -7,7 +9,7 @@ This file contains various python functions to work with a set of test alerts.
 It relies on our broker-utils library which can be installed using `pip install pgb-broker-utils`.
 (You may want to activate a Conda environment before installing.)
 
-## Setup
+### Setup
 
 ```python
 import os
@@ -35,14 +37,14 @@ def _get_avro_paths(dir):
     return (p for p in dir.glob("*.avro"))
 ```
 
-## Download the set of test alerts
+### Download the set of test alerts
 
 ```python
 # download the files
 gcp_utils.cs_download_file(alert_dir, testing_bucket_id)
 ```
 
-## Load an alert as a dict
+### Load an alert as a dict
 
 Once you load the alert into a dictionary you can use it to test pieces of your function locally.
 
@@ -66,7 +68,7 @@ alert_dict = data_utils.decode_alert(
 )
 ```
 
-## Publish alert to a topic
+### Publish alert to a topic
 
 ```python
 # fill in a topic name
diff --git a/docs/source/working-notes/troyraen/branch-tests/update_broker_utils.md b/docs/source/working-notes/troyraen/branch-tests/update_broker_utils.md
index 10f3e2f5..73478f34 100644
--- a/docs/source/working-notes/troyraen/branch-tests/update_broker_utils.md
+++ b/docs/source/working-notes/troyraen/branch-tests/update_broker_utils.md
@@ -1,6 +1,8 @@
-# update_broker_utils
+# docs/source/working-notes/troyraen/branch-tests/update_broker_utils.md
 
-## Setup
+## update_broker_utils
+
+### Setup
 
 ```bash
 survey=ztf
@@ -12,7 +14,7 @@ project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
 survey, testid = "ztf", "brokerutils"
 ```
 
-## Deploy instance
+### Deploy instance
 
 ```bash
 cd broker/setup_broker
@@ -20,7 +22,7 @@ teardown=False
 ./setup_broker.sh "$testid" "$teardown" "$survey"
 ```
 
-## Publish test alerts
+### Publish test alerts
 
 Following [Alerts for Testing](https://pitt-broker.readthedocs.io/en/develop/broker/alerts-for-testing.html).
 
@@ -111,7 +113,7 @@ gcloud compute instances add-metadata "$vm_name" \
 gcloud compute instances start "$vm_name"
 ```
 
-## Query test results
+### Query test results
 
 According to the [README](https://pitt-broker.readthedocs.io/en/develop/working-notes/troyraen/alerts-for-testing/README.html) included with the test alerts, we expect:
 
@@ -158,7 +160,7 @@ for dataset, tables in datasets.items():
 
 ```
 
-## broker-utils not installing on night-conductor
+### broker-utils not installing on night-conductor
 
 Solution: use a Conda environment with Python 3.7
 
diff --git a/docs/source/working-notes/troyraen/v0.6.0/test-pubsub-pricing.md b/docs/source/working-notes/troyraen/v0.6.0/test-pubsub-pricing.md
index 4cbaff64..66dd3362 100644
--- a/docs/source/working-notes/troyraen/v0.6.0/test-pubsub-pricing.md
+++ b/docs/source/working-notes/troyraen/v0.6.0/test-pubsub-pricing.md
@@ -1,6 +1,8 @@
-# Testing Pub/Sub tutorial from external account.
+# docs/source/working-notes/troyraen/v0.6.0/test-pubsub-pricing.md
 
-## Summary:
+## Testing Pub/Sub tutorial from external account.
+
+### Summary:
 
 Date of tests: 8/6/2021 (note there were no live ZTF streams Aug 5-7)
 
@@ -21,21 +23,21 @@ There is no way for this account to be charged.
 Billing is disabled and I have never created a billing account.
 I can't even see a billing report because I don't have a billing account.
 
-## Initial thoughts:
+### Initial thoughts:
 
 - Testing pricing, free tier, egress, msg delivery
 - What happens if you don't enable billing and reach the Free Tier limit?
 - Does "message delivery" mean delivered to the subscription or delivered to the user (on pull request)?
     - Note on [Pub/Sub pricing page](https://cloud.google.com/pubsub/pricing#pubsub) it says: "Storage of unacknowledged messages does not result in fees."
 
-## Outline:
+### Outline:
 
 - streamed ~300,000 messages to the subscription projects/my-pgb-project-3/subscriptions/test
 - setup a compute engine in Germany to pull the messages
     - compute engine is in pgb project since can't do VMs with free accounts. setup credentials to project my-pgb-project-3 following [v0.5.0/external-connection.md](../v0.5.0/external-connection.md)
 - pulled the messages from the test subscription and wrote a sampling of message sizes to file
 
-## Code to do it:
+### Code to do it:
 
 Use the stream-looper VM to publish the messages.
 
diff --git a/docs/source/working-notes/troyraen/v0.6.0/test-stream-looper.md b/docs/source/working-notes/troyraen/v0.6.0/test-stream-looper.md
index d2db3335..c642b2aa 100644
--- a/docs/source/working-notes/troyraen/v0.6.0/test-stream-looper.md
+++ b/docs/source/working-notes/troyraen/v0.6.0/test-stream-looper.md
@@ -1,4 +1,6 @@
-# Test pricing and functionality of stream-looper long term
+# docs/source/working-notes/troyraen/v0.6.0/test-stream-looper.md
+
+## Test pricing and functionality of stream-looper long term
 
 Started stream-looper around 11:00 am ET on Aug 7, publishing 1 alert/sec.