Add doc lint check to pre-commit hooks

.github/workflows/ci.yaml

@@ -20,7 +20,7 @@ jobs:
       - name: run lint checks
         run: poetry run black --check alpaca/ tests/
       - name: build doc html to lint for errors
-        run: pushd docs && poetry run make html SPHINXOPTS="-W" && popd
+        run: ./tools/scripts/generate-docs.sh
 
   tests-ci:
     strategy:

.pre-commit-config.yaml

@@ -22,3 +22,9 @@ repos:
         entry: "poetry run pytest"
         pass_filenames: false
         always_run: true
+      - id: doc check
+        name: sphinx doc check
+        language: system
+        entry: "./tools/scripts/generate-docs.sh"
+        pass_filenames: false
+        always_run: true

alpaca/broker/client.py

@@ -50,6 +50,8 @@ def __init__(
         base_url: BaseURL = (
             BaseURL.BROKER_SANDBOX if sandbox else BaseURL.BROKER_PRODUCTION
         )
+
+        # TODO: Actually check raw_data everywhere
         super().__init__(api_key, secret_key, api_version, base_url, sandbox, raw_data)
 
     def create_account(self, account_data: AccountCreationRequest) -> Account:
@@ -116,5 +118,17 @@ def update_account(
 
         return Account(**response)
 
-    def delete_account(self) -> Account:
-        pass
+    def delete_account(self, account_id: Union[UUID, str]) -> None:
+        """
+        Delete an Account by its id.
+
+        As the api itself returns a 204 on success this function returns nothing in the successful case and will raise
+        and exception in any other case.
+
+        Args:
+            account_id (Union[UUID, str]): the id of the Account you wish to delete. str values will attempt to be
+            upcast to UUID to validate.
+
+        Returns:
+            None:
+        """

alpaca/broker/models.py

@@ -441,6 +441,7 @@ def to_request_fields(self) -> dict:
           {contact: {city: None, country: None...}, etc}
         we generate just:
           {trusted_contact:{given_name: "new value"}}
+
         Returns:
             dict: a dict containing any set fields
         """

tests/broker/test_broker_client_accounts_routes.py

@@ -398,3 +398,7 @@ def test_update_account_validates_non_empty_request(reqmock, client: BrokerClien
         client.update_account(account_id, update_data)
 
     assert str(e.value) == "update_data must contain at least 1 field to change"
+
+
+def test_delete_account(reqmock, client: BrokerClient):
+    pass

tools/scripts/generate-docs.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -e
+
+#make sure we're in the root of our repo
+pushd "$(dirname "$0")"/../../docs >>/dev/null
+
+set +e
+
+#clean any local files to prevent cached errors
+poetry run make clean
+
+#run make html with a flag to make sphinx treat warnings as errors instead of generating incomplete docs
+poetry run make html SPHINXOPTS="-W"