From 728bb6ee85eaa6aada9463df1c1df80b72fa6b19 Mon Sep 17 00:00:00 2001 From: Ryan McKenna Date: Thu, 20 Aug 2026 11:26:22 -0700 Subject: [PATCH] Add API Reference tab to ReadTheDocs documentation. PiperOrigin-RevId: 967945359 --- README.md | 4 + docs/_templates/autosummary/class.rst | 46 +++++++++ docs/api_reference.rst | 133 ++++++++++++++++++++++++++ docs/conf.py | 22 +++++ docs/index.rst | 40 ++++++++ dpsynth/__init__.py | 8 +- 6 files changed, 252 insertions(+), 1 deletion(-) create mode 100644 docs/_templates/autosummary/class.rst create mode 100644 docs/api_reference.rst create mode 100644 docs/index.rst diff --git a/README.md b/README.md index c5cbeed..5901237 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ # DPSynth: Differentially Private Synthetic Tabular Data +[![Documentation](https://readthedocs.org/projects/dpsynth/badge/?version=latest)](https://dpsynth.readthedocs.io/en/latest/) + DPSynth is a library for differentially private synthetic tabular data generation. Given a sensitive dataset of records defined w.r.t. a single-table schema, our library can generate a synthetic version of the dataset, preserving the structure and statistical properties of the source data while satisfying differential privacy. +📖 **[Full documentation on ReadTheDocs](https://dpsynth.readthedocs.io/en/latest/)** + > [!WARNING] > **This library is under active development.** APIs may change without notice, > and you may encounter bugs, rough edges, or incomplete features. For standard diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000..6f53f21 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,46 @@ +.. Copyright 2026 Google LLC +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. 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. + +{{ fullname | escape | underline }} + +.. autoclass:: {{ fullname }} + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource + :special-members: __call__ + + {% block methods %} + {% if methods %} + .. rubric:: Methods + + .. autosummary:: + :nosignatures: + {% for item in methods %} + ~{{ name }}.{{ item }} + {% endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: Attributes + + .. autosummary:: + :nosignatures: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {% endfor %} + {% endif %} + {% endblock %} diff --git a/docs/api_reference.rst b/docs/api_reference.rst new file mode 100644 index 0000000..ff3baff --- /dev/null +++ b/docs/api_reference.rst @@ -0,0 +1,133 @@ +.. Copyright 2026 Google LLC +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. 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. + +############# +API Reference +############# + +This page documents the public Python API for DPSynth. The library is organized +into three layers: + +- **Domain specification** — describing the schema of your tabular data. +- **Constraints** — optional cross-attribute restrictions on generated values. +- **Mechanisms** — configuring and running differentially private synthesis. + +.. contents:: On this page + :local: + :depth: 2 + +---- + +Domain Specification (``dpsynth.domain``) +========================================== + +.. currentmodule:: dpsynth.domain + +The ``domain`` module provides dataclasses for describing the schema of a +tabular dataset. Each column is represented by one of the attribute types +below. Pass a mapping of column names to attribute objects as the ``domains`` +argument to :class:`~dpsynth.TabularSynthesizer`. + +.. autosummary:: + :toctree: _autosummary + :nosignatures: + :template: autosummary/class.rst + + CategoricalAttribute + NumericalAttribute + OpenSetCategoricalAttribute + FreeFormTextAttribute + +---- + +Cross-Attribute Constraints (``dpsynth.constraints``) +====================================================== + +.. currentmodule:: dpsynth.constraints + +The ``constraints`` module lets you express known relationships between columns +so that the synthetic data honours them. Pass a list of +:class:`~dpsynth.constraints.Constraint` objects as +``cross_attribute_constraints`` to :class:`~dpsynth.TabularSynthesizer`. + +.. autosummary:: + :toctree: _autosummary + :nosignatures: + :template: autosummary/class.rst + + Constraint + +---- + +Mechanism Abstractions (``dpsynth.api``) +========================================= + +.. currentmodule:: dpsynth.api + +These abstract base classes define the three-phase *construct → calibrate → run* +protocol shared by all DPSynth mechanisms. + +.. autosummary:: + :toctree: _autosummary + :nosignatures: + :template: autosummary/class.rst + + MechanismConfig + CalibratedMechanism + +---- + +Discrete Mechanisms (``dpsynth.discrete_mechanisms``) +====================================================== + +.. currentmodule:: dpsynth.discrete_mechanisms + +Discrete mechanisms operate on pre-discretized integer datasets +(:class:`mbi.Dataset`). :class:`TabularSynthesizer` applies them internally +after encoding your DataFrame. Use them directly only if you already have a +discrete dataset. + +Mechanism Configs +----------------- + +Each config class corresponds to a published DP synthesis algorithm. Pass one +as the ``discrete_mechanism`` argument to :class:`~dpsynth.TabularSynthesizer`, +or use :class:`~dpsynth.discrete_mechanisms.DiscreteConfig` to add one-way +marginal measurement and domain compression. + +.. autosummary:: + :toctree: _autosummary + :nosignatures: + :template: autosummary/class.rst + + AIMConfig + MSTConfig + IndependentConfig + DirectConfig + SWIFTConfig + AIMGDPConfig + +DiscreteConfig +-------------- + +:class:`DiscreteConfig` wraps any of the mechanism configs above with one-way +marginal pre-measurement and optional domain compression. It is the recommended +entry point when you have a pre-discretized table. + +.. autosummary:: + :toctree: _autosummary + :nosignatures: + :template: autosummary/class.rst + + DiscreteConfig diff --git a/docs/conf.py b/docs/conf.py index e6cbd0e..c15e515 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,3 +1,17 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. + # Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: @@ -18,11 +32,19 @@ extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'myst_parser', # For markdown support ] +autosummary_generate = True +autodoc_default_options = { + 'members': True, + 'undoc-members': False, + 'show-inheritance': True, +} + # templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..96dce10 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,40 @@ +.. Copyright 2026 Google LLC +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. 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. + +################################################## + DPSynth: Differentially Private Synthetic Data +################################################## + +.. include:: index.md + :parser: myst_parser.sphinx_ + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + data_and_terminology + in_memory_api + +.. toctree:: + :maxdepth: 2 + :caption: Guides + + processing_lifecycle + contributors_guide + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + api_reference diff --git a/dpsynth/__init__.py b/dpsynth/__init__.py index 5cf8c88..5d87272 100644 --- a/dpsynth/__init__.py +++ b/dpsynth/__init__.py @@ -15,12 +15,18 @@ """Public API for DPSynth.""" # pylint: disable=g-importing-member -__version__ = '0.2.0' +__version__ = '0.3.0' from dpsynth import api +from dpsynth import constraints from dpsynth import discrete_mechanisms from dpsynth import domain +from dpsynth.api import CalibratedMechanism +from dpsynth.api import MechanismConfig +from dpsynth.constraints import Constraint from dpsynth.data_generation_v3 import TabularConfig from dpsynth.data_generation_v3 import TabularMechanism from dpsynth.data_generation_v3 import TabularSynthesizer from dpsynth.domain import CategoricalAttribute +from dpsynth.domain import FreeFormTextAttribute from dpsynth.domain import NumericalAttribute +from dpsynth.domain import OpenSetCategoricalAttribute