Api ref docs deployment (#108)

* integrate sphinx docs into docusaurus

* integrate sphinx docs into docusaurus

* disable flaky test

* Automatically reformatting code

* test docs build

* fix docs deployment gha

* tested that docs are ready to deploy

* clean up

* address pr feedback

* remove docs

* set unBrokenMarkdownLinks to throw

* fix pr

* small patch

* update readme

* final touches

---------

Co-authored-by: Auto-format Bot <[email protected]>

.github/workflows/cicd.yaml

@@ -83,6 +83,28 @@ jobs:
       - name: Build website
         run: npm run build
 
+    # Checks that the API reference docs built with shpinx build
+  test-api-reference-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: get code 
+        uses: actions/checkout@v3
+      - name: install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: install poetry 
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{ env.POETRY_VERSION }}
+
+      - name: Install dependencies 
+        run: make install-sphinx-deps
+
+      - name: Build API documentation
+        run: |
+          make apidocs
+
   # Run integration tests against the API (only on the main branch, though). The comprehensive
   # version runs a matrix of python versions for better coverage.
   test-comprehensive:
@@ -190,6 +212,7 @@ jobs:
     if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
     needs:
       - test-comprehensive
+      - test-api-reference-docs
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -205,7 +228,9 @@ jobs:
       - name: Install dependencies
         run: npm install
       - name: Build website
-        run: npm run build
+        run: |
+          cd ..
+          make docs-comprehensive 
       - name: Deploy website (if on main branch)
         # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
         uses: peaceiris/actions-gh-pages@v3

Makefile

@@ -72,12 +72,25 @@ sphinx-help:
 # The .PHONY directive tells make that `apidocs` and `html` are labels for 
 # commands. `apidocs: html` allows us to generate docs by running 
 # `make apidocs` instead. 
-.PHONY: apidocs html 
-
+.PHONY: docs-comprehensive apidocs html 
+
+# Start an interactive server to test docs locally
+develop-docs-comprehensive: docs-comprehensive 
+	cd docs && npm start 
+
+## Builds docs comprehensively (integrating API reference docs built 
+## with sphinx into the docusaurus docs). 
+docs-comprehensive: apidocs 
+	rm -rf docs/static/api-reference-docs
+	rm -rf docs/build/api-reference-docs
+	mkdir docs/static/api-reference-docs
+	mv build/html/* docs/static/api-reference-docs/
+
+	cd docs && npm run build 
+
 apidocs: 
 	poetry run make html 
 
 html:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
-	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
+.package-lock.json
 
 # Misc
 .DS_Store

docs/README.md

@@ -9,9 +9,7 @@ The docs are included with the SDK so that we can automate testing of the code s
 Doc changes are published automatically when they're merged to main.  To preview changes, build and host the site locally.  You'll need a reasonably modern version of `npm` and then:
 
 ```
-npm install
-npm run build  # looks for any errors
-npm start  # starts interactive server
+make develop-docs-comprehensive
 ```
 
 and then open [http://localhost:3000/python-sdk](http://localhost:3000/python-sdk).

docs/docs/api-reference/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "API Reference",
+  "position": 5,
+  "collapsed": false
+}

docs/docs/api-reference/api-reference.md

@@ -0,0 +1,3 @@
+# API Reference 
+
+Click [here](pathname:///python-sdk/api-reference-docs/) to access a detailed documentation of the SDK with all available methods. 

docs/docusaurus.config.js

@@ -25,7 +25,7 @@ const config = {
   trailingSlash: false,
 
   onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
+  onBrokenMarkdownLinks: "throw",
 
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
@@ -98,6 +98,11 @@ const config = {
             label: "Applications",
             position: "left",
           },
+          {
+            href: "pathname:///python-sdk/api-reference-docs/",
+            label: 'API Reference',
+            position: "left",
+          },
           {
             href: "https://github.com/groundlight/python-sdk",
             label: "GitHub",

sphinx_docs/conf.py

@@ -45,4 +45,4 @@ def get_version_name() -> str:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
+html_static_path = ["_static"]