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 = [