Build documentation with mkdocs (#38)

* Add minimum viable mkdocs configuration

* Add examples section

* Add links to api docs and overviews

* Get api docs up and running

* Add `__all__` to `__init__.py` files to include correct classes

This is just a first step to including the correct items in the api docs

* Exclude test modules from docs

* Use correct module

* Add docs deployment workflow

* Include all correct modules/classes/functions

* Fix button rendering

* Fix formatting, including admonitions

* Fix broken link

* Use README.md as homepage for docs

* Fix links

* Remove debug triggers from docs deployment workflow

* Remove deprecated api docs

* Fix triggers

* Move docs requirements to common location

* Only trigger on pushes to master

* Remove unnecessary newline characters

* Move docs location to default `docs` directory

Author: smokestacklightnin

.github/workflows/cd-docs.yml

@@ -0,0 +1,49 @@
+name: deploy-docs
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - 'master'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: |
+            setup.py
+
+      - name: Save time for cache for mkdocs
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Caching
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install Dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Deploy to GitHub Pages
+        if: (github.event_name != 'pull_request')
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          mkdocs gh-deploy --force
+
+      - name: Build docs to check for errors
+        if: (github.event_name == 'pull_request')
+        run: |
+          mkdocs build

README.md

@@ -16,7 +16,7 @@ examples of struct2tensor in action and an introduction to the main
 concepts. You can
 [run the notebook in your browser](https://colab.research.google.com/github/google/struct2tensor/blob/master/examples/prensor_playground.ipynb)
 through Google's colab environment, or [download the
-file](examples/prensor_playground.ipynb) to run it in your own Jupyter
+file](https://github.com/google/struct2tensor/tree/master/g3doc/examples/prensor_playground.ipynb) to run it in your own Jupyter
 environment.
 
 
@@ -99,8 +99,9 @@ struct2tensor needs a couple of custom TensorFlow ops to function. If you train
 a model with struct2tensor and wants to serve it with TensorFlow Serving, the
 TensorFlow Serving binary needs to link with those custom ops. We have a
 pre-built docker image that contains such a binary. The `Dockerfile` is
-available at `tools/tf_serving_docker/Dockerfile`. The image is available at
-`gcr.io/tfx-oss-public/s2t_tf_serving`.
+available at [`tools/tf_serving_docker/Dockerfile`](https://github.com/google/struct2tensor/blob/master/struct2tensor/tools/tf_serving_docker/Dockerfile).
+The image is available at
+[`gcr.io/tfx-oss-public/s2t_tf_serving`](gcr.io/tfx-oss-public/s2t_tf_serving).
 
 Please see the `Dockerfile` for details. But in brief, the image exposes port
 8500 as the gRPC endpoint and port 8501 as the REST endpoint. You can set

g3doc/api_docs/python/_toc.yaml docs/api_docs/python/_toc.yamlg3doc/api_docs/python/_toc.yaml renamed to docs/api_docs/python/_toc.yaml

@@ -0,0 +1,3 @@
+# `expression_impl`
+
+::: struct2tensor.expression_impl

docs/api_docs/python/expression_impl/expression_impl.md

@@ -0,0 +1,58 @@
+# Module: expression_impl
+
+<div class="buttons-wrapper">
+  <a class="md-button" target="_blank" href=
+	  "https://github.com/google/struct2tensor/blob/master/struct2tensor/expression_impl/__init__.py">
+    <div class="buttons-content">
+      <img width="32px" src=
+	   "https://www.tensorflow.org/images/GitHub-Mark-32px.png">
+      View source on GitHub
+    </div>
+  </a>
+</div>
+
+The modules in this file should be accessed like the following:
+
+```python
+import struct2tensor as s2t
+from struct2tensor import expression_impl
+
+s2t.expression_impl.apply_schema
+```
+
+## Modules
+
+[`apply_schema`][struct2tensor.expression_impl.apply_schema] module: Apply a schema to an expression.
+
+[`broadcast`][struct2tensor.expression_impl.broadcast] module: Methods for broadcasting a path in a tree.
+
+[`depth_limit`][struct2tensor.expression_impl.depth_limit] module: Caps the depth of an expression.
+
+[`filter_expression`][struct2tensor.expression_impl.filter_expression] module: Create a new expression that is a filtered version of an original one.
+
+[`index`][struct2tensor.expression_impl.index] module: get_positional_index and get_index_from_end methods.
+
+[`map_prensor`][struct2tensor.expression_impl.map_prensor] module: Arbitrary operations from sparse and ragged tensors to a leaf field.
+
+[`map_prensor_to_prensor`][struct2tensor.expression_impl.map_prensor_to_prensor] module: Arbitrary operations from prensors to prensors in an expression.
+
+[`map_values`][struct2tensor.expression_impl.map_values] module: Maps the values of various leaves of the same child to a single result.
+
+[`parquet`][struct2tensor.expression_impl.parquet] module: Apache Parquet Dataset.
+
+[`placeholder`][struct2tensor.expression_impl.placeholder] module: Placeholder expression.
+
+[`project`][struct2tensor.expression_impl.project] module: project selects a subtree of an expression.
+
+[`promote`][struct2tensor.expression_impl.promote] module: Promote an expression to be a child of its grandparent.
+
+[`promote_and_broadcast`][struct2tensor.expression_impl.promote_and_broadcast] module: promote_and_broadcast a set of nodes.
+
+[`proto`][struct2tensor.expression_impl.proto] module: Expressions to parse a proto.
+
+[`reroot`][struct2tensor.expression_impl.reroot] module: Reroot to a subtree, maintaining an input proto index.
+
+[`size`][struct2tensor.expression_impl.size] module: Functions for creating new size or has expression.
+
+[`slice_expression`][struct2tensor.expression_impl.slice_expression] module: Implementation of slice.
+

docs/api_docs/python/expression_impl/index.md

@@ -0,0 +1,67 @@
+# Module: s2t
+
+<div class="buttons-wrapper">
+  <a class="md-button" target="_blank" href=
+	  "https://github.com/google/struct2tensor/blob/master/struct2tensor/__init__.py">
+    <div class="buttons-content">
+      <img width="32px" src=
+	   "https://www.tensorflow.org/images/GitHub-Mark-32px.png">
+      View source on GitHub
+    </div>
+  </a>
+</div>
+
+Import core names for struct2tensor.
+
+## Classes
+
+[`class ChildNodeTensor`][struct2tensor.ChildNodeTensor]: The value of an intermediate node.
+
+[`class Expression`][struct2tensor.Expression]: An expression represents the calculation of a prensor object.
+
+[`class LeafNodeTensor`][struct2tensor.LeafNodeTensor]: The value of a leaf node.
+
+[`class Path`][struct2tensor.Path]: A representation of a path in the expression.
+
+[`class Prensor`][struct2tensor.Prensor]: A expression of NodeTensor objects.
+
+[`class RootNodeTensor`][struct2tensor.RootNodeTensor]: The value of the root.
+
+## Functions
+
+[`calculate_prensors(...)`][struct2tensor.calculate_prensors]: Gets the prensor value of the expressions.
+
+[`calculate_prensors_with_graph(...)`][struct2tensor.calculate_prensors_with_graph]: Gets the prensor value of the expressions and the graph used.
+
+[`calculate_prensors_with_source_paths(...)`][struct2tensor.calculate_prensors_with_source_paths]: Returns a list of prensor trees, and proto summaries.
+
+[`create_expression_from_file_descriptor_set(...)`][struct2tensor.create_expression_from_file_descriptor_set]: Create an expression from a 1D tensor of serialized protos.
+
+[`create_expression_from_prensor(...)`][struct2tensor.create_expression_from_prensor]: Gets an expression representing the prensor.
+
+[`create_expression_from_proto(...)`][struct2tensor.create_expression_from_proto]: Create an expression from a 1D tensor of serialized protos.
+
+[`create_path(...)`][struct2tensor.create_path]: Create a path from an object.
+
+[`create_prensor_from_descendant_nodes(...)`][struct2tensor.create_prensor_from_descendant_nodes]: Create a prensor from a map of paths to NodeTensor.
+
+[`create_prensor_from_root_and_children(...)`][struct2tensor.create_prensor_from_root_and_children]
+
+[`get_default_options(...)`][struct2tensor.get_default_options]: Get the default options.
+
+[`get_options_with_minimal_checks(...)`][struct2tensor.get_options_with_minimal_checks]: Options for calculation with minimal runtime checks.
+
+[`get_ragged_tensor(...)`][struct2tensor.get_ragged_tensor]: Get a ragged tensor for a path. (deprecated)
+
+[`get_ragged_tensors(...)`][struct2tensor.get_ragged_tensors]: Gets ragged tensors for all the leaves of the prensor expression. (deprecated)
+
+[`get_sparse_tensor(...)`][struct2tensor.get_sparse_tensor]: Gets a sparse tensor for path p. (deprecated)
+
+[`get_sparse_tensors(...)`][struct2tensor.get_sparse_tensors]: Gets sparse tensors for all the leaves of the prensor expression. (deprecated)
+
+## Type Aliases
+
+[`NodeTensor`][struct2tensor.NodeTensor]
+
+[`Step`][struct2tensor.Step]
+

docs/api_docs/python/s2t/index.md

@@ -0,0 +1,4 @@
+# `s2t`
+
+::: struct2tensor.struct2tensor
+