docs: Generate docs using sphinx-autoapi (#52)

NillionNetwork · Nov 13, 2024 · cfddbb9 · cfddbb9
1 parent 7c622cc
commit cfddbb9
Show file tree

Hide file tree

Showing 23 changed files with 130 additions and 202 deletions.
diff --git a/docs/_source/nada_dsl.audit.abstract.rst b/docs/_source/nada_dsl.audit.abstract.rst
diff --git a/docs/_source/nada_dsl.audit.report.rst b/docs/_source/nada_dsl.audit.report.rst
diff --git a/docs/_source/nada_dsl.audit.strict.rst b/docs/_source/nada_dsl.audit.strict.rst
diff --git a/docs/_source/nada_dsl.circuit_io.rst b/docs/_source/nada_dsl.circuit_io.rst
diff --git a/docs/_source/nada_dsl.compile.rst b/docs/_source/nada_dsl.compile.rst
diff --git a/docs/_source/nada_dsl.compiler_frontend.rst b/docs/_source/nada_dsl.compiler_frontend.rst
diff --git a/docs/_source/nada_dsl.nada_types.rst b/docs/_source/nada_dsl.nada_types.rst
diff --git a/docs/_source/nada_dsl.operations.rst b/docs/_source/nada_dsl.operations.rst
diff --git a/docs/_source/nada_dsl.rst b/docs/_source/nada_dsl.rst
diff --git a/docs/_source/nada_dsl.source_ref.rst b/docs/_source/nada_dsl.source_ref.rst
diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t
diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,78 +12,85 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+
+sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
 
 # The name and version are retrieved from ``pyproject.toml`` in the root
 # directory.
 import toml
-with open('../pyproject.toml') as pyproject_file:
+
+with open("../pyproject.toml") as pyproject_file:
     pyproject_data = toml.load(pyproject_file)
-project = pyproject_data['project']['name']
-version = pyproject_data['project']['version']
+project = pyproject_data["project"]["name"]
+version = pyproject_data["project"]["version"]
 release = version
 
 # The copyright year and holder information is retrieved from the
 # ``LICENSE`` file.
 try:
     import re
-    with open('../LICENSE', 'r') as license_file:
-        license_string = license_file.read().split('Copyright (c) ')[1]
+
+    with open("../LICENSE", "r") as license_file:
+        license_string = license_file.read().split("Copyright (c) ")[1]
     year = license_string[:4]
-    author = license_string[5:].split('\n')[0]
-    copyright = year + ', ' + re.sub(r"\.$", "", author) # Period already in HTML.
+    author = license_string[5:].split("\n")[0]
+    copyright = year + ", " + re.sub(r"\.$", "", author)  # Period already in HTML.
 except:
-    year = ''
-    author = ''
-    copyright = ''
+    year = ""
+    author = ""
+    copyright = ""
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.viewcode'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "autoapi.extension",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build']
+exclude_patterns = ["_build"]
 
 # Options to configure autodoc extension behavior.
-autodoc_member_order = 'bysource'
+autodoc_member_order = "bysource"
 autodoc_default_options = {
-    'special-members': True,
-    'exclude-members': ','.join([
-        '__init__',
-        '__weakref__',
-        '__module__',
-        '__hash__',
-        '__dict__',
-        '__annotations__',
-        '__dataclass_params__',
-        '__dataclass_fields__',
-        '__match_args__',
-        '__repr__',
-
-    ])
+    "special-members": True,
+    "exclude-members": ",".join(
+        [
+            "__init__",
+            "__weakref__",
+            "__module__",
+            "__hash__",
+            "__dict__",
+            "__annotations__",
+            "__dataclass_params__",
+            "__dataclass_fields__",
+            "__match_args__",
+            "__repr__",
+        ]
+    ),
 }
 autodoc_preserve_defaults = True
 
+autoapi_dirs = ["../nada_dsl"]
+
 # Allow references/links to definitions found in the Python documentation.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
+    "python": ("https://docs.python.org/3", None),
 }
 
 # Do not display fully qualified names.
@@ -95,12 +102,11 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options for Read the Docs.
 html_theme_options = {
-    'display_version': True,
-    'collapse_navigation': True,
-    'navigation_depth': 1,
-    'titles_only': True
+    "collapse_navigation": True,
+    "navigation_depth": 4,
+    "titles_only": True,
 }
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,2 +1,12 @@
 .. include:: ../README.rst
-.. include:: toc.rst
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Reference      
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/toc.rst b/docs/toc.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -8,12 +8,18 @@ version = "0.7.1"
 description = "Nillion Nada DSL to create Nillion MPC programs."
 requires-python = ">=3.10"
 readme = "README.pyproject.md"
-dependencies = ["asttokens~=2.4", "richreports~=0.2", "parsial~=0.1", "sortedcontainers~=2.4", "typing_extensions~=4.12.2"]
+dependencies = [
+    "asttokens~=2.4",
+    "richreports~=0.2",
+    "parsial~=0.1",
+    "sortedcontainers~=2.4",
+    "typing_extensions~=4.12.2",
+]
 classifiers = ["License :: OSI Approved :: Apache Software License"]
 license = { file = "LICENSE" }
 
 [project.optional-dependencies]
-docs = ["toml~=0.10.2", "sphinx>=5,<9", "sphinx-rtd-theme>=1.0,<3.1"]
+docs = ["toml~=0.10.2", "sphinx>=5,<9", "sphinx-rtd-theme>=1.0,<3.1", "sphinx-autoapi~=3.3.2"]
 test = ["pytest>=7.4,<9.0", "pytest-cov>=4,<7"]
 lint = ["pylint>=2.17,<3.4"]
 
@@ -28,6 +34,7 @@ dev-dependencies = [
     "toml~=0.10.2",
     "sphinx>=5,<9",
     "sphinx-rtd-theme>=1.0,<3.1",
+    "sphinx-autoapi~=3.3.2",
     "pytest>=7.4,<9.0",
     "pytest-cov>=4,<7",
     "pylint>=2.17,<3.4",

diff --git a/nada_dsl/audit_strict_test.py → tests/audit_strict_test.py b/nada_dsl/audit_strict_test.py → tests/audit_strict_test.py
diff --git a/nada_dsl/compile_test.py → tests/compile_test.py b/nada_dsl/compile_test.py → tests/compile_test.py
diff --git a/nada_dsl/compiler_frontend_test.py → tests/compiler_frontend_test.py b/nada_dsl/compiler_frontend_test.py → tests/compiler_frontend_test.py
diff --git a/nada_dsl/nada_type_test.py → tests/nada_type_test.py b/nada_dsl/nada_type_test.py → tests/nada_type_test.py
diff --git a/nada_dsl/scalar_type_test.py → tests/scalar_type_test.py b/nada_dsl/scalar_type_test.py → tests/scalar_type_test.py