Merge pull request #39 from invertase/update-sphinx-docs-setup

refactor: rework for better generated reference docs

Author: taeold

.github/workflows/ci.yaml

@@ -15,9 +15,9 @@ jobs:
         python: ["3.10"]
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
       - name: Install dependencies
@@ -38,9 +38,9 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
         with:
           python-version: "3.10"
       - name: Install dependencies
@@ -58,3 +58,29 @@ jobs:
         run: |
           source venv/bin/activate
           python3.10 -m mypy .
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python3.10 -m venv venv
+          source venv/bin/activate 
+          pip3 install --upgrade pip 
+          python3.10 -m pip install -r requirements.txt
+          python3.10 setup.py install
+      - name: Generate Reference Docs
+        run: |
+          source venv/bin/activate
+          mkdir ./docs/build
+          ./docs/generate.sh --out=./docs/build/ --pypath=src/
+      - uses: actions/upload-artifact@v3
+        name: Upload Docs Preview
+        with:
+          name: reference-docs
+          path: ./docs/build/

docs/generate.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 # Copyright 2022 Google Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -37,40 +37,40 @@ THEMEPATH=$(dirname $0)/theme
 THEMEPATH=$(realpath "$THEMEPATH")
 
 if [[ $(uname) == "Darwin" ]]; then
-  TEMPARGS=$(/Users/$(id -un)/homebrew/opt/gnu-getopt/bin/getopt -o o:p:b:t: --long out:,pypath:,sphinx-build:,themepath: -- "$@")
+  TEMPARGS=$($(brew --prefix)/opt/gnu-getopt/bin/getopt -o o:p:b:t: --long out:,pypath:,sphinx-build:,themepath: -- "$@")
 else
   TEMPARGS=$(getopt -o o:p:b:t: --long out:,pypath:,sphinx-build:,themepath: -- "$@")
   getopt = getopt
 fi
 eval set -- "$TEMPARGS"
 
 while true; do
-    case "$1" in
-        -o|--out)
-            OUTDIR=$(realpath "$2")
-            shift 2
-            ;;
-        -p|--pypath)
-            PYTHONPATH=$(realpath "$2"):"$PYTHONPATH"
-            shift 2
-            ;;
-        -b|--sphinx-build)
-            SPHINXBIN=$(realpath "$2")
-            shift 2
-            ;;
-        -t|--themepath)
-            THEMEPATH=$(realpath "$2")
-            shift 2
-            ;;
-        --)
-            shift
-            break
-            ;;
-        *)
-           echo Error
-           exit 1
-           ;;
-    esac
+  case "$1" in
+  -o | --out)
+    OUTDIR=$(realpath "$2")
+    shift 2
+    ;;
+  -p | --pypath)
+    PYTHONPATH=$(realpath "$2"):"$PYTHONPATH"
+    shift 2
+    ;;
+  -b | --sphinx-build)
+    SPHINXBIN=$(realpath "$2")
+    shift 2
+    ;;
+  -t | --themepath)
+    THEMEPATH=$(realpath "$2")
+    shift 2
+    ;;
+  --)
+    shift
+    break
+    ;;
+  *)
+    echo Error
+    exit 1
+    ;;
+  esac
 done
 
 TARGET="$1"
@@ -82,20 +82,21 @@ if [[ "$OUTDIR" == "" ]]; then
 fi
 
 TITLE="Firebase Python SDK for Cloud Functions"
-PY_MODULES='firebase_functions firebase_functions.core firebase_functions.https firebase_functions.params firebase_functions.db'
+PY_MODULES='firebase_functions firebase_functions.core firebase_functions.https firebase_functions.params firebase_functions.db firebase_functions.options firebase_functions.pubsub firebase_functions.storage'
 DEVSITE_PATH='/docs/reference/functions-python'
 
 #
 # Set up temporary project
 #
 PROJDIR=$(mktemp -d)
 echo Created project directory: "$PROJDIR"
-pushd "$PROJDIR" > /dev/null
+pushd "$PROJDIR" >/dev/null
 mkdir _build
 
 cat >conf.py <<EOL
 import devsite_translator.html
 
+exclude_patterns = ['venv/**']
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
 source_suffix = '.rst'
 master_doc = 'index'
@@ -110,8 +111,8 @@ def setup(app):
   app.set_translator('html', devsite_translator.html.FiresiteHTMLTranslator)
 EOL
 
-for m in ${PY_MODULES};
-do cat >"$m".rst <<EOL
+for m in ${PY_MODULES}; do
+  cat >"$m".rst <<EOL
 ${m} module
 ===============================================================================
 
@@ -133,7 +134,7 @@ ${TITLE}
 EOL
 
 for m in ${PY_MODULES}; do
-  echo "   ${m}" >> index.rst
+  echo "   ${m}" >>index.rst
 done
 
 #
@@ -170,8 +171,8 @@ toc:
   path: ${DEVSITE_PATH}/
 EOL
 for m in ${PY_MODULES}; do
-  echo "- title: ${m}" >> "$TOC"
-  echo "  path: ${DEVSITE_PATH}/${m}" >> "$TOC"
+  echo "- title: ${m}" >>"$TOC"
+  echo "  path: ${DEVSITE_PATH}/${m}" >>"$TOC"
 done
 
-popd > /dev/null
+popd >/dev/null

requirements.txt

@@ -2,6 +2,8 @@ Flask>=2.2.2
 PyYAML>=6.0
 pytest>=7.1.2
 setuptools>=63.4.2
-pylint>=2.15.3
+pylint>=2.16.1
 pytest-cov>=3.0.0
-mypy>=0.971
+mypy>=1.0.0
+sphinx>=6.1.3
+sphinxcontrib-napoleon>=0.7

setup.py

@@ -20,7 +20,7 @@
 
 install_requires = [
     'flask>=2.1.2', 'functions-framework>=3.0.0', 'firebase-admin>=6.0.0',
-    'pyyaml>=6.0', 'typing-extensions>=4.3.0', 'cloudevents==1.9.0',
+    'pyyaml>=6.0', 'typing-extensions>=4.4.0', 'cloudevents==1.9.0',
     'flask-cors>=3.0.10', 'pyjwt[crypto]>=2.5.0'
 ]
 

src/firebase_functions/core.py

@@ -65,20 +65,3 @@ class CloudEvent(_typing.Generic[T]):
     The resource, provided by source, that this event relates to
     """
 
-
-@_dataclass.dataclass(frozen=True)
-class Change(_typing.Generic[T]):
-    """
-    * The Functions interface for events that change state, such as
-    * Realtime Database `on_value_written`.
-    """
-
-    before: T
-    """
-    The state of data before the change.
-    """
-
-    after: T
-    """
-    The state of data after the change.
-    """

src/firebase_functions/db.py

@@ -11,8 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-
 """
 Module for Cloud Functions that are triggered by the Firebase Realtime Database.
 """
@@ -21,18 +19,36 @@
 import functools as _functools
 import typing as _typing
 import datetime as _dt
-import firebase_functions.options as _options
 import firebase_functions.private.util as _util
 import firebase_functions.core as _core
 import cloudevents.http as _ce
-from firebase_functions.core import Change  # Exported for user ease of typing events
+
+from firebase_functions.options import DatabaseOptions
 
 _event_type_written = "google.firebase.database.ref.v1.written"
 _event_type_created = "google.firebase.database.ref.v1.created"
 _event_type_updated = "google.firebase.database.ref.v1.updated"
 _event_type_deleted = "google.firebase.database.ref.v1.deleted"
 
 
+@_dataclass.dataclass(frozen=True)
+class Change(_typing.Generic[_core.T]):
+    """
+    * The Functions interface for events that change state, such as
+    * Realtime Database `on_value_written`.
+    """
+
+    before: _core.T
+    """
+    The state of data before the change.
+    """
+
+    after: _core.T
+    """
+    The state of data after the change.
+    """
+
+
 @_dataclass.dataclass(frozen=True)
 class Event(_core.CloudEvent[_core.T]):
     """
@@ -87,7 +103,7 @@ def _db_endpoint_handler(
         # Merge delta into data to generate an 'after' view of the data.
         if isinstance(before, dict) and isinstance(after, dict):
             after = _util.prune_nones({**before, **after})
-        database_event_data = _core.Change(
+        database_event_data = Change(
             before=before,
             after=after,
         )
@@ -111,7 +127,7 @@ def _db_endpoint_handler(
     func(database_event)
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_util.copy_func_kwargs(DatabaseOptions)
 def on_value_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
     Event handler which triggers when data is created, updated, or deleted in Realtime Database.
@@ -124,8 +140,14 @@ def on_value_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(event: Event[Change[object]]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_written_inner_decorator(func: _C1):
 
@@ -143,7 +165,7 @@ def on_value_written_wrapped(raw: _ce.CloudEvent):
     return on_value_written_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_util.copy_func_kwargs(DatabaseOptions)
 def on_value_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
     Event handler which triggers when data is updated in Realtime Database.
@@ -156,8 +178,14 @@ def on_value_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(event: Event[Change[object]]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_updated_inner_decorator(func: _C1):
 
@@ -175,7 +203,7 @@ def on_value_updated_wrapped(raw: _ce.CloudEvent):
     return on_value_updated_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_util.copy_func_kwargs(DatabaseOptions)
 def on_value_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
     Event handler which triggers when data is created in Realtime Database.
@@ -185,10 +213,17 @@ def on_value_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     .. code-block:: python
 
         @on_value_created(reference="*")
-        def example(event):
+        def example(event: Event[object]):
           pass
+
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_created_inner_decorator(func: _C2):
 
@@ -206,7 +241,7 @@ def on_value_created_wrapped(raw: _ce.CloudEvent):
     return on_value_created_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_util.copy_func_kwargs(DatabaseOptions)
 def on_value_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
     Event handler which triggers when data is deleted in Realtime Database.
@@ -219,8 +254,14 @@ def on_value_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
       def example(event: Event[object]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_deleted_inner_decorator(func: _C2):