Update docs action (#311)

* Update env

* Update action to fail on warnings

* Fix api.rst warning

* Add a few aliases

* More docstring cleanup

* Add langchain ref

* Minor fixes

* More doc links

* More fixes

* More fixes

* More link updates

* More doc fixes

* Update method skipping logic

* Typo fix

* More docs fixes

* Throw warnings

* Use pdoc instead of pdev

* Update deprecated field

* More skip methods

* Add pyptoject toml watch

* Add conditionals on workflow

* Add env options directly to command

* Use pixi command, which now has opts in the env var

* Bump elm version

* Minor conf update

* Copilot review updates

* Update command name

Author: ppinchuk

.github/workflows/docs.yml

@@ -4,8 +4,18 @@ permissions: write-all
 
 on:
   pull_request:
+    paths:
+      - compass/**
+      - .github/workflows/docs.yml
+      - pyproject.toml
+      - pixi.lock
   push:
     branches: [main]
+    paths:
+      - compass/**
+      - .github/workflows/docs.yml
+      - pyproject.toml
+      - pixi.lock
   release:
     types: [created, published]
   workflow_dispatch:
@@ -26,15 +36,11 @@ jobs:
         with:
           pixi-version: v0.50.2
           locked: true
-          cache: false
+          cache: false  # Don't use cache because we use the ``pdoc`` environment
           environments: pdoc
 
       - name: Build Docs
-        # Make documentation with warnings as errors.
-        # The stricter Sphinx options below are currently disabled due to known documentation warnings.
-        # Once all warnings are resolved, consider enabling this line to catch documentation issues early.
-        # run: SPHINXOPTS="-W --keep-going -n" pixi run -e pdoc make-html
-        run: pixi run -e pdoc make-html
+        run: pixi run -e pdoc python-doc  # This errors on warnings
 
       - name: deploy
         uses: peaceiris/actions-gh-pages@v4.0.0

.github/workflows/lint-python.yml

@@ -6,13 +6,15 @@ on:
       - 'gh-pages'
     paths:
       - compass/**
-      - pyproject.toml
       - .github/workflows/lint-python.yml
+      - pyproject.toml
+      - pixi.lock
   pull_request:
     paths:
       - compass/**
-      - pyproject.toml
       - .github/workflows/lint-python.yml
+      - pyproject.toml
+      - pixi.lock
 
 jobs:
   lint:

compass/common/base.py

@@ -66,7 +66,7 @@ def setup_graph_no_nodes(d_tree_name="Unknown Decision Tree", **kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph with no nodes but with global keywords set.
     """
     feat = kwargs.get("feature_id", kwargs.get("feature", kwargs.get("url")))
@@ -180,7 +180,7 @@ def setup_base_setback_graph(**kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """
@@ -256,7 +256,7 @@ def setup_participating_owner(**kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """
@@ -373,7 +373,7 @@ def setup_graph_extra_restriction(is_numerical=True, **kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """
@@ -762,7 +762,7 @@ def setup_graph_permitted_use_districts(**kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """
@@ -858,14 +858,15 @@ class BaseTextExtractor:
         "the relevant content appears within a table, return the entire "
         "table, including headers and footers, exactly as formatted."
     )
+    """System message for text extraction LLM calls"""
     _USAGE_LABEL = LLMUsageCategory.DOCUMENT_ORDINANCE_SUMMARY
 
     def __init__(self, llm_caller):
         """
 
         Parameters
         ----------
-        llm_caller : compass.llm.LLMCaller
+        llm_caller : LLMCaller
             LLM Caller instance used to extract ordinance info with.
         """
         self.llm_caller = llm_caller

compass/common/tree.py

@@ -31,16 +31,15 @@ class AsyncDecisionTree(DecisionTree):
            graph.
     Key Relationships:
         Inherits from :class:`~elm.tree.DecisionTree` to add ``async``
-        capabilities. Uses a
-        :class:`~compass.llm.calling.ChatLLMCaller` for LLm queries.
+        capabilities. Uses a ChatLLMCaller for LLm queries.
     """
 
     def __init__(self, graph, usage_sub_label=None):
         """
 
         Parameters
         ----------
-        graph : nx.DiGraph
+        graph : networkx.DiGraph
             Directed acyclic graph where nodes are LLM prompts and edges
             are logical transitions based on the response. Must have
             high-level graph attribute "chat_llm_caller" which is a
@@ -138,7 +137,7 @@ async def async_run(self, node0="init"):
 
         Returns
         -------
-        out : str | None
+        out : str or None
             Final response from LLM at the leaf node or ``None`` if an
             ``AttributeError`` was raised during execution.
         """

compass/extraction/apply.py

@@ -32,20 +32,19 @@ async def check_for_ordinance_info(
     Parameters
     ----------
     doc : elm.web.document.BaseDocument
-        A document potentially containing ordinance information. Note
-        that if the document's attrs contains the
-        ``"contains_ord_info"`` key, it will not be processed. To force
-        a document to be processed by this function, remove that key
-        from the documents attrs.
+        A document instance (PDF, HTML, etc) potentially containing
+        ordinance information. Note that if the document's ``attrs``
+        has the ``"contains_ord_info"`` key, it will not be processed.
+        To force a document to be processed by this function, remove
+        that key from the documents ``attrs``.
     tech : str
         Technology of interest (e.g. "solar", "wind", etc). This is
         used to set up some document validation decision trees.
-    text_splitter : obj
-        Instance of an object that implements a `split_text` method.
-        The method should take text as input (str) and return a list
-        of text chunks. Langchain's text splitters should work for this
-        input.
-    usage_tracker : compass.services.usage.UsageTracker, optional
+    text_splitter : LCTextSplitter, optional
+        Optional Langchain text splitter (or subclass instance), or any
+        object that implements a `split_text` method. The method should
+        take text as input (str) and return a list of text chunks.
+    usage_tracker : UsageTracker, optional
         Optional tracker instance to monitor token usage during
         LLM calls. By default, ``None``.
 
@@ -131,7 +130,7 @@ async def extract_date(doc, model_config, usage_tracker=None):
     ----------
     doc : elm.web.document.BaseDocument
         A document potentially containing date information.
-    usage_tracker : compass.services.usage.UsageTracker, optional
+    usage_tracker : UsageTracker, optional
         Optional tracker instance to monitor token usage during
         LLM calls. By default, ``None``.
 
@@ -165,20 +164,17 @@ async def extract_ordinance_text_with_llm(
     doc : elm.web.document.BaseDocument
         A document known to contain ordinance information. This means it
         must contain an ``"ordinance_text"`` key in the attrs. You can
-        run :func:`~compass.extraction.apply.check_for_ordinance_info`
+        run :func:`check_for_ordinance_info`
         to have this attribute populated automatically for documents
         that are found to contain ordinance data. Note that if the
         document's attrs does not contain the ``"ordinance_text"``
         key, you will get an error.
-    text_splitter : obj
-        Instance of an object that implements a `split_text` method.
-        The method should take text as input (str) and return a list
-        of text chunks. Langchain's text splitters should work for this
-        input.
-    extractor : compass.extraction.ordinance.WindOrdinanceTextExtractor
-        Instance of
-        :class:`~compass.extraction.ordinance.WindOrdinanceTextExtractor`
-        used for ordinance text extraction.
+    text_splitter : LCTextSplitter, optional
+        Optional Langchain text splitter (or subclass instance), or any
+        object that implements a `split_text` method. The method should
+        take text as input (str) and return a list of text chunks.
+    extractor : WindOrdinanceTextExtractor
+        Object used for ordinance text extraction.
     original_text_key : str
         String corresponding to the `doc.attrs` key containing the
         original text (before extraction).
@@ -237,11 +233,10 @@ async def extract_ordinance_text_with_ngram_validation(
         that are found to contain ordinance data. Note that if the
         document's attrs does not contain the ``"ordinance_text"``
         key, it will not be processed.
-    text_splitter : obj
-        Instance of an object that implements a `split_text` method.
-        The method should take text as input (str) and return a list
-        of text chunks. Langchain's text splitters should work for this
-        input.
+    text_splitter : LCTextSplitter, optional
+        Optional Langchain text splitter (or subclass instance), or any
+        object that implements a `split_text` method. The method should
+        take text as input (str) and return a list of text chunks.
     original_text_key : str
         String corresponding to the `doc.attrs` key containing the
         original text (before extraction).

compass/extraction/date.py

@@ -35,20 +35,19 @@ class DateExtractor:
         "if you are confident that they represent the latest date this "
         "ordinance was enacted/updated"
     )
+    """System message for date extraction LLM calls"""
 
     def __init__(self, structured_llm_caller, text_splitter=None):
         """
 
         Parameters
         ----------
-        structured_llm_caller : compass.llm.StructuredLLMCaller
-            StructuredLLMCaller instance. Used for structured validation
-            queries.
-        text_splitter : TextSplitter, optional
-            Optional
-            :class:`langchain_text_splitters.character.TextSplitter`
-            text splitter instance to attach to doc (used for
-            splitting out pages in an HTML document).
+        structured_llm_caller : StructuredLLMCaller
+            Instance used for structured validation queries.
+        text_splitter : LCTextSplitter, optional
+            Optional text splitter (or subclass instance, or any object
+            that implements a `split_text` method) to attach to doc
+            (used for splitting out pages in an HTML document).
             By default, ``None``.
         """
         self.slc = structured_llm_caller

compass/extraction/features.py

@@ -33,6 +33,7 @@ class SetbackFeatures:
         ],
         "water": ["lakes", "reservoirs", "streams", "rivers", "wetlands"],
     }
+    """Aliases for mutually-exclusive setback features"""
     FEATURES_AS_IGNORE = {
         "structures": "structures",
         "property line": "property lines",
@@ -41,6 +42,7 @@ class SetbackFeatures:
         "transmission": "transmission lines",
         "water": "wetlands",
     }
+    """Features as they should appear in ignore phrases"""
     FEATURE_CLARIFICATIONS = {
         "structures": "",
         "property line": (
@@ -54,6 +56,7 @@ class SetbackFeatures:
         "transmission": "",
         "water": "",
     }
+    """Clarifications to add to feature prompts"""
 
     def __init__(self):
         self._validate_descriptions()

compass/extraction/solar/graphs.py

@@ -18,7 +18,7 @@ def setup_graph_sef_types(**kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """
@@ -156,7 +156,7 @@ def setup_multiplier(**kwargs):
 
     Returns
     -------
-    nx.DiGraph
+    networkx.DiGraph
         Graph instance that can be used to initialize an
         `elm.tree.DecisionTree`.
     """