feat: generate docs for both fal sdk and client (#320)

.github/workflows/docs.yaml

@@ -18,13 +18,14 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install -e 'projects/fal[docs]'
         pip install -e 'projects/fal_client[docs]'
 
     - name: Build documentation
-      run: make -C projects/fal_client/docs html
+      run: make docs
 
     - name: Deploy to GitHub Pages
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: projects/fal_client/docs/_build/html
+        publish_dir: docs/_build/html

.gitignore

@@ -25,3 +25,5 @@ dmypy.json
 /coverage.xml
 /.coverage
 tmp/
+
+/docs/

projects/fal/.gitignore

@@ -1 +1,2 @@
 /src/fal/_fal_version.py
+/docs/*

projects/fal/Makefile

@@ -0,0 +1,24 @@
+MAKEFILE_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+
+SPHINXOPTS    = --fresh-env
+SPHINXBUILD   = sphinx-build
+SPHINXAPIDOC  = sphinx-apidoc
+SOURCEDIR     = $(MAKEFILE_DIR)/docs
+BUILDDIR      = $(MAKEFILE_DIR)/docs/_build
+PROJECTDIR    = $(MAKEFILE_DIR)/src/fal
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean apidoc html docs
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+apidoc:
+	$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)" "$(PROJECTDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+docs: apidoc html

projects/fal/docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'fal_sdk'
+copyright = '2024, FAL Team'
+author = 'FAL Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_autodoc_typehints'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

projects/fal/docs/index.rst

@@ -0,0 +1,18 @@
+.. fal_sdk documentation master file, created by
+   sphinx-quickstart on Wed Oct  2 05:09:49 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+fal_sdk documentation
+=====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules

projects/fal/pyproject.toml

@@ -60,6 +60,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+    "sphinx-autodoc-typehints",
+]
 test = [
     "pytest<8",
     "pytest-asyncio",
@@ -68,7 +73,7 @@ test = [
     "boto3",
 ]
 dev = [
-    "fal[test]",
+    "fal[docs,test]",
     "openapi-python-client>=0.14.1,<1",
 ]
 

projects/fal_client/.gitignore

@@ -1 +1 @@
-/docs/_build
+/docs/*

projects/fal_client/Makefile

@@ -0,0 +1,24 @@
+MAKEFILE_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+
+SPHINXOPTS    = --fresh-env
+SPHINXBUILD   = sphinx-build
+SPHINXAPIDOC  = sphinx-apidoc
+SOURCEDIR     = $(MAKEFILE_DIR)/docs
+BUILDDIR      = $(MAKEFILE_DIR)/docs/_build
+PROJECTDIR    = $(MAKEFILE_DIR)/src/fal_client
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean apidoc html docs
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+apidoc:
+	$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)" "$(PROJECTDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+docs: apidoc html

projects/fal_client/pyproject.toml

@@ -22,6 +22,7 @@ dependencies = [
 [project.optional-dependencies]
 docs = [
     "sphinx",
+    "sphinx-rtd-theme",
     "sphinx-autodoc-typehints",
 ]
 test = [