docs: remove pdoc assets, build & host them in readthedocs (#632)

* docs: generate pdoc assets as a readthedocs pre_build job

* Delete already-existing pdoc assets

* Move pdoc output to _readthedocs/html/

* Try pointing to a different path

* Create a dummy html file, change 'jobs' to 'commands'

* Roll back to 'jobs', 'commands' deactivates all default jobs

* Attempt to fix path

* Try post build instead of pre

* Try again with _readthedocs/html folder

* Try changing _readthedocs path

* Move back to pre build

* Try local pip checkout for sqlmesh

Author: georgesittas

.circleci/config.yml

@@ -21,20 +21,6 @@ jobs:
       - run:
           name: Publish Python package
           command: make publish
-      - run:
-          name: Update API Documentation
-          command: |
-            pip install pdoc sqlmesh
-            make api-docs
-            git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git config --local user.name "github-actions[bot]"
-            git add docs
-            git commit -m "CI: Auto-generated documentation" -a | exit 0
-      - run:
-          name: Deploy API Documentation
-          command: |
-            GITHUB_TOKEN="$GITHUB_TOKEN" \
-            git push origin main
 
   gh-release:
     docker:

.readthedocs.yaml

@@ -4,6 +4,10 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.8"
+  jobs:
+    pre_build:
+      - pip install -e .
+      - make api-docs
 
 mkdocs:
   configuration: mkdocs.yml

Makefile

@@ -72,7 +72,7 @@ docs-serve:
 	mkdocs serve
 
 api-docs:
-	python pdoc/cli.py -o docs
+	python pdoc/cli.py -o docs/_readthedocs/html/
 
 api-docs-serve:
 	python pdoc/cli.py

docs/_readthedocs/html/.keep

@@ -2,3 +2,4 @@ mkdocs==1.4.2
 mkdocs-include-markdown-plugin==4.0.3
 mkdocs-material==9.0.5
 mkdocs-material-extensions==1.1.1
+pdoc==13.0.1