clean up dbt docs

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
     - id: trailing-whitespace
 
 - repo: https://github.com/charliermarsh/ruff-pre-commit
-  rev: v0.0.284
+  rev: v0.6.2
   hooks:
     - id: ruff
 

CHANGELOG.md

@@ -4,7 +4,8 @@
 
 - Fix bug where `exog` and `group_by` did not handle `str` inputs e.g. `exog="x"`.
 - Fix bug where `group_by` for `method='fwl'` with exactly 1 exog variable did not work. (Explanation: `method='fwl'` dispatches to a different macro for the special case of 1 exog variable, and `group_by` was not implemented correctly here.)
-- Fix bug where `safe` mode did not work for `method='chol'`
+- Fix bug where `safe` mode did not work for `method='chol'`.
+- Improved docs by hiding everything except `ols()`, improved description of `ols()` macro, and added missing arg.
 
 ### `0.2.4`
 

README.md

@@ -193,7 +193,8 @@ def ols(
     format_options: Optional[dict[str, Any]] = None,
     group_by: Optional[Union[str, list[str]]] = None,
     alpha: Optional[Union[float, list[float]]] = None,
-    method: Literal['chol', 'fwl'] = 'chol'
+    method: Literal['chol', 'fwl'] = 'chol',
+    method_options: Optional[dict[str, Any]] = None
 ):
     ...
 ```

macros/schema.yml

@@ -28,7 +28,31 @@ macros:
       ```
       {% endraw %}
 
-      The macro renders a subquery; in some database engines, such as Postgres, it is required to alias all subqueries.
+      You may also select from a CTE; in this case, just pass a string referencing the CTE:
+
+      {% raw %}
+      ```sql
+      {{
+        config(
+          materialized="table"
+        )
+      }}
+      with my_data as (
+        select * from {{ ref('simple_matrix') }}
+      )
+      select * from {{
+        dbt_linreg.ols(
+          table='my_data',
+          endog='y',
+          exog=['xa', 'xb', 'xc'],
+          format='long',
+          format_options={'round': 5}
+        )
+      }}
+      ```
+      {% endraw %}
+
+      The macro renders a subquery, inclusive of parentheses.
 
       Please see the README / full documentation for more information: [https://dwreeves.github.io/dbt_linreg/](https://dwreeves.github.io/dbt_linreg/)
     arguments:
@@ -53,6 +77,9 @@ macros:
       - name: format_options
         type: dict
         description: See **Formats and format options** section in the README for more.
+      - name: group_by
+        type: string or list of numbers
+        description: If specified, the regression will be grouped by these variables, and individual regressions will run on each group.
       - name: alpha
         type: number or list of numbers
         description: If not null, the regression will be run as a ridge regression with a penalty of `alpha`. See **Notes** section in the README for more information.
@@ -62,18 +89,36 @@ macros:
       - name: method_options
         type: dict
         description: Options specific to the estimation method. See **Methods and method options** in the README for more.
-  # Everything down here is just for intermediary calculations.
-  # Better to hide this stuff to reduce confusion when reading docs.
+  # Everything down here is just for intermediary calculations or helper functions.
+  # There is no point to showing these in the docs.
   # The truly curious can just look at the source code.
+  #
+  # Please generate the below with the following command:
+  # >>> python scripts.py gen-hide-macros-yaml
   - name: _alias_exog
     docs:
       show: false
   - name: _alias_gb_cols
     docs:
       show: false
+  - name: _cell_or_alias
+    docs:
+      show: false
+  - name: _cholesky_decomposition
+    docs:
+      show: false
+  - name: _filter_and_center_if_alpha
+    docs:
+      show: false
+  - name: _filter_if_alpha
+    docs:
+      show: false
   - name: _format_wide_variable_column
     docs:
       show: false
+  - name: _forward_substitution
+    docs:
+      show: false
   - name: _gb_cols
     docs:
       show: false
@@ -83,21 +128,84 @@ macros:
   - name: _maybe_round
     docs:
       show: false
+  - name: _ols_0var
+    docs:
+      show: false
+  - name: _ols_1var
+    docs:
+      show: false
+  - name: _ols_chol
+    docs:
+      show: false
+  - name: _ols_fwl
+    docs:
+      show: false
+  - name: _orth_x_intercept
+    docs:
+      show: false
+  - name: _orth_x_slope
+    docs:
+      show: false
+  - name: _regress_or_alias
+    docs:
+      show: false
+  - name: _safe_sqrt
+    docs:
+      show: false
   - name: _strip_quotes
     docs:
       show: false
+  - name: _traverse_intercepts
+    docs:
+      show: false
+  - name: _traverse_slopes
+    docs:
+      show: false
   - name: _unalias_gb_cols
     docs:
       show: false
+  - name: bigquery___safe_sqrt
+    docs:
+      show: false
+  - name: default___cell_or_alias
+    docs:
+      show: false
+  - name: default___maybe_round
+    docs:
+      show: false
+  - name: default___regress_or_alias
+    docs:
+      show: false
+  - name: default___safe_sqrt
+    docs:
+      show: false
   - name: default__regress
     docs:
       show: false
+  - name: duckdb___cell_or_alias
+    docs:
+      show: false
+  - name: duckdb___regress_or_alias
+    docs:
+      show: false
   - name: final_select
     docs:
       show: false
+  - name: postgres___maybe_round
+    docs:
+      show: false
+  - name: redshift___maybe_round
+    docs:
+      show: false
   - name: regress
     docs:
       show: false
+  - name: snowflake___cell_or_alias
+    docs:
+      show: false
+  - name: snowflake___regress_or_alias
+    docs:
+      show: false
   - name: snowflake__regress
     docs:
       show: false