Documentation / Docstring Syntax Fixes (#1719)

* Fix missing string closure in write_tests.rst

* Fix sphinx warning "title overline too short"

* autoclass :: -> autoclass::

* Fix sphinx warning "title underline too short"

* Fix sphinx autodoc AttributeError parsing utilities.dbt

* Fix sphinx error "Error in "code-block" directive"

* Fix sphinx critical error unexpected section title from improper use of markdown code blocks in reStructuredText

* Fix sphinx error "Unexpected indentation"

* Fix sphinx warning "Inline strong start-string without end-string"

* Fix sphinx warning "Duplicate explicit target name"

* add missing toc entries

* remove trailing whitespace from all files

* ensure all files have newline at end of file

* convert tabs to spaces in remaining two files

* fix improperly-formatted links in zoom documentation

* remove unecessary parentheses in method reference

* replace tab characters with spaces in getting_set_up.rst

* `Args:` -> `Args`: -> Args: (and Returns)

* fix no-blank-line-after-section

* fix no-blank-line-before-section

* fix missing-blank-line-after-last-section

* fix overindented-section

* install censusgeocode

* fix note syntax

* fix autoclass references

* resolve attempted slackclient import

* add mock import for pytz and airtable

* fix MobilizeAmerica path

* fix inherited-members indentation

* don't use autodoc module/class name hinting

* add :members: to all autoclasses

* try to fix remaining autodoc import warnings

* save docs-build artifact on circleci (for testing)

* resolve SyntaxWarning for \* in tofrom.py

* fix artifact upload path

* improve docstring formatting of actblue.py

* resolving more docstring syntax errors

* Inline strong start-string without end-string.

* Duplicate explicit target name

* Unknown target name

* ERROR: Unknown directive type "notes".

* Block quote ends without a blank line

* fix Unexpected indentation

* Duplicate explicit target name

* Enumerated list ends without a blank line

* Title underline too short

* autodoc: failed to import class 'dbtRunnerParsons

* Error parsing content block for the "list-table" directive: two-level bullet list expected, but row 4 does not contain a second-level bullet list.

* Definition list ends without a blank line

* unexpected unindent.

* Bullet list ends without a blank line

* link formatting

* fix Unknown target name: "user"

* Inline strong start-string without end-string

* fixing a lot of errors and warnings

* fix malformed table

* exclude sphinx output from git

* Upgrade CircleCI config

* more docstring formatting

* improve return/yield docstring formatting

* don't try to overwrite existing .venv in circleci

---------

Co-authored-by: Shauna Gordon-McKeon <shaunagm@gmail.com>

Author: bmos

.circleci/config.yml

@@ -1,23 +1,15 @@
-# Python CircleCI 2.0 configuration file
-#
-# Check https://circleci.com/docs/2.0/language-python/ for more details
-#
-
-version: 2
+version: 2.1
 
 workflows:
   version: 2
   docs-build:
     jobs:
       - docs-build
       - docs-build-deploy:
-          filters:
-            branches:
-              only: main
+          requires:
+            - docs-build
 
 jobs:
-
-  # Documentation CI
   docs-build:
     docker:
       - image: cimg/python:3.13
@@ -58,35 +50,21 @@ jobs:
 
   docs-build-deploy:
     docker:
-      - image: cimg/python:3.13-node
+      - image: cimg/node:current
 
     steps:
       - checkout
 
-      - restore_cache:
-          keys:
-            - v2-dependencies-python3.13-{{ checksum "pyproject.toml" }}-{{ checksum "setup.py" }}
-            # fallback to using the latest cache if no exact match is found
-            - v2-dependencies-python3.13-
+      - attach_workspace:
+          at: .
 
       - run:
-          name: Install parsons
-          # Note that we the circleci node image installs stuff with a user "circleci", rather
-          # than root. So we need to tell npm where to install stuff.
+          name: Validate build artifacts
           command: |
-            npm set prefix=/home/circleci/npm
-            npm install -g --silent gh-pages@2.0.1
-
-            uv sync \
-              --upgrade \
-              --no-default-groups \
-              --group docs \
-              --all-extras
-
-      - save_cache:
-          paths:
-            - ./venv
-          key: v2-dependencies-python3.13-{{ checksum "pyproject.toml" }}-{{ checksum "setup.py" }}
+            if [ ! -f docs/html/index.html ]; then
+              echo "Error: docs/html/index.html not found! Build might have failed."
+              exit 1
+            fi
 
       - add_ssh_keys:
           # This SSH key is "CircleCI Docs" in https://github.com/move-coop/parsons/settings/keys
@@ -95,24 +73,9 @@ jobs:
             - '9a:ec:4d:2b:c3:45:b2:f5:55:ca:0b:2b:36:e2:7f:df'
 
       - run:
-          name: Build and deploy docs
-          # When running gh-pages, we specify to include dotfiles, so we pick up the .nojerkyll file.
-          # (This file tell Github Pages that we want to include all files in docs/, including those
-          # that start with an underscore like _static/).
+          name: Deploy docs
           command: |
-            uv sync \
-              --no-default-groups \
-              --group docs \
-              --all-extras
-
-            cd docs/
-            uv venv make deploy_docs
-
-            cd ..
-
             git config user.email "ci-build@movementcooperative.org"
             git config user.name "ci-build"
 
-            export PATH=/home/circleci/npm/bin:$PATH
-
-            gh-pages --dotfiles --message "[skip ci] Updates" --dist docs
+            npx gh-pages@2.0.1 --dist docs/html --message "[skip ci] Updates" --dotfiles

.github/ISSUE_TEMPLATE/bug-report.md

@@ -29,4 +29,4 @@ Add any other context about the problem here.
 
 
 ## Priority
-Please indicate whether fixing this bug is high, medium, or low priority for you. If the issue is time-sensitive for you, please let us know when you need it addressed by.
+Please indicate whether fixing this bug is high, medium, or low priority for you. If the issue is time-sensitive for you, please let us know when you need it addressed by.

.github/ISSUE_TEMPLATE/proposed-feature-addition.md

@@ -23,4 +23,4 @@ assignees: ''
 
 
 ## Priority
-<!--- Please indicate whether adding this feature is high, medium, or low priority for you. If the issue is time-sensitive for you, please let us know when you want it addressed by. -->
+<!--- Please indicate whether adding this feature is high, medium, or low priority for you. If the issue is time-sensitive for you, please let us know when you want it addressed by. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,12 @@
 ## What is this change?
 - (List out the changes.)
-- (Link to any relevant Github issues or Slack discussion)
+- (Link to any relevant Github issues or Slack discussion.)
+
+## Breaking changes (if needed)
+- (List out any changes to the API that may cause breaks for developer implementation.)
 
 ## Considerations for discussion
 - (List out any significant design decisions that were made and why.)
 
 ## How to test the changes (if needed)
-- (How should a reviewer test this functionality)
+- (How should a reviewer test this functionality.)

.github/release.yml

@@ -19,4 +19,4 @@ changelog:
     #     -🎉-first-PR
     - title: Other Changes
       labels:
-        - "*"
+        - "*"

.github/workflows/dependency-review.yml

@@ -23,4 +23,4 @@ jobs:
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
-      - uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261
+      - uses: actions/dependency-review-action@05fe4576374b728f0c523d6a13d64c25081e0803

.github/workflows/python-checks.yml

@@ -50,7 +50,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - if: matrix.resolution != 'limited-dependencies'
         continue-on-error: ${{ contains(matrix.python-version, '3.14') }}
@@ -114,7 +114,7 @@ jobs:
           python-version: '3.13'
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - run: >-
           uv sync
@@ -178,7 +178,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - env:
             PARSONS_LIMITED_DEPENDENCIES: 'TRUE'
@@ -218,7 +218,7 @@ jobs:
           python-version: '3.13'
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - run: >-
           uv sync
@@ -263,7 +263,7 @@ jobs:
           python-version: '3.13'
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - run: >-
           uv sync
@@ -285,7 +285,7 @@ jobs:
           -o results.sarif
           .
 
-      - uses: github/codeql-action/upload-sarif@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2
+      - uses: github/codeql-action/upload-sarif@89a39a4e59826350b863aa6b6252a07ad50cf83e
         if: ( success() || failure() ) && contains('["success", "failure"]', steps.run-ruff-sarif.outcome)
         with:
           sarif_file: results.sarif
@@ -322,7 +322,7 @@ jobs:
           python-version: '3.13'
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - run: >-
           uv sync
@@ -340,7 +340,7 @@ jobs:
           --format 'sarif'
           --output 'results.sarif'
 
-      - uses: github/codeql-action/upload-sarif@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2
+      - uses: github/codeql-action/upload-sarif@89a39a4e59826350b863aa6b6252a07ad50cf83e
         if: ( success() || failure() ) && contains('["success", "failure"]', steps.run-bandit-sarif.outcome)
         with:
           sarif_file: results.sarif
@@ -422,7 +422,7 @@ jobs:
           python-version: '3.13'
           cache: pip
 
-      - uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+      - uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - run: >-
           uv sync

.github/workflows/release.yml

@@ -27,7 +27,7 @@ jobs:
           cache: pip
 
       - name: Install uv
-        uses: install-pinned/uv@c57eeccb84c14c060f224d6b4dcef7b645f05277
+        uses: install-pinned/uv@05d9162df91b0a72301801afd144d0b8b525e0b3
 
       - name: Install parsons
         run: >-

.github/workflows/security_scorecard.yml

@@ -62,6 +62,6 @@ jobs:
           results_format: sarif
           publish_results: true
 
-      - uses: github/codeql-action/upload-sarif@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2
+      - uses: github/codeql-action/upload-sarif@89a39a4e59826350b863aa6b6252a07ad50cf83e
         with:
-          sarif_file: results.sarif
+          sarif_file: results.sarif

.gitignore

@@ -66,6 +66,7 @@ instance/
 
 # Sphinx documentation
 docs/html
+docs/_build/html
 
 # PyBuilder
 target/