Skip to content

Commit 93e096c

Browse files
abbottdev-krollabbottdev-kroll
committed
add sphinx-js gen
1 parent 8cc873d commit 93e096c

10 files changed

Lines changed: 2986 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,15 @@ This project uses [`@protobuf-ts/plugin`](https://github.com/timostamm/protobuf-
4747
- If you see TypeScript errors about missing modules, ensure your `tsconfig.json` includes the `src/athena` directory and restart your IDE/tsserver.
4848

4949
---
50+
51+
Building Documentation
52+
To build the documentation:
53+
54+
# Install uv if not already installed
55+
curl -LsSf https://astral.sh/uv/install.sh | sh
56+
57+
# Sync dependencies and build
58+
uv sync
59+
cd docs
60+
make html
61+
The built documentation will be available in docs/_build/html/index.html.

‎docs/Makefile‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@uv run $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Install dependencies
18+
install:
19+
uv sync
20+
21+
# Install development dependencies
22+
install-dev:
23+
uv sync --extra dev
24+
25+
# Lock dependencies
26+
lock:
27+
uv lock
28+
29+
# Update dependencies
30+
update:
31+
uv sync --upgrade
32+
33+
# Build HTML documentation
34+
html:
35+
@uv run $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
36+
@echo
37+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
38+
39+
# Build documentation and watch for changes
40+
livehtml:
41+
uv run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
42+
43+
# Clean build directory
44+
clean:
45+
rm -rf "$(BUILDDIR)"
46+
47+
# Build PDF documentation (requires LaTeX)
48+
latexpdf:
49+
@uv run $(SPHINXBUILD) -b latex "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(SPHINXOPTS) $(O)
50+
@echo "Running LaTeX files through pdflatex..."
51+
$(MAKE) -C "$(BUILDDIR)/latex" all-pdf
52+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
53+
54+
# Build EPUB documentation
55+
epub:
56+
@uv run $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)/epub" $(SPHINXOPTS) $(O)
57+
@echo
58+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
59+
60+
# Check documentation for common issues
61+
linkcheck:
62+
@uv run $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) $(O)
63+
@echo
64+
@echo "Link check complete; look for any errors in the above output " \
65+
"or in $(BUILDDIR)/linkcheck/output.txt."
66+
67+
# Check documentation for spelling errors (requires sphinxcontrib-spelling)
68+
spelling:
69+
@uv run $(SPHINXBUILD) -b spelling "$(SOURCEDIR)" "$(BUILDDIR)/spelling" $(SPHINXOPTS) $(O)
70+
@echo
71+
@echo "Spell check complete; look for any errors in the above output " \
72+
"or in $(BUILDDIR)/spelling/."
73+
74+
# Build documentation in different formats
75+
all: html epub latexpdf
76+
@echo "Documentation built in multiple formats."
77+
78+
# Development setup
79+
dev-setup:
80+
uv sync --extra dev
81+
@echo "Development environment set up. Use 'make livehtml' for auto-rebuilding docs."
82+
83+
# Sync and build
84+
sync-build: install html
85+
@echo "Dependencies synced and documentation built."
86+
87+
# Catch-all target: route all unknown targets to Sphinx using the new
88+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
89+
%: Makefile
90+
@uv run $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/images/favicon/favicon-32x32.png‎

358 Bytes
Loading

‎docs/_static/images/favicon/icon.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎docs/_static/images/logo/Resolver_Lettermark_Main.png‎

11.7 KB
Loading

‎docs/_static/images/logo/Resolver_Lettermark_White.png‎

11.1 KB
Loading

‎docs/conf.py‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
# Configuration file for the Sphinx documentation builder.
10+
"""Sphinx configuration file for Athena NodeJS SDK documentation."""
11+
12+
import sys
13+
from datetime import datetime, timezone
14+
from pathlib import Path
15+
16+
# Add the project source directory to the Python path
17+
sys.path.insert(0, str(Path("../athena").resolve()))
18+
19+
# Project information
20+
project = 'Athena Classifier NodeJS SDK'
21+
copyright = f"{datetime.now(timezone.utc).year}, Crisp"
22+
author = "Crisp"
23+
release = "1.0.0"
24+
25+
js_language = 'typescript'
26+
js_source_path = '../src/'
27+
jsdoc_config_path = '../typedoc.json'
28+
29+
# Extensions
30+
extensions = [
31+
'sphinx_js',
32+
"sphinx.ext.autodoc",
33+
"sphinx.ext.napoleon",
34+
"sphinx.ext.viewcode",
35+
"sphinx.ext.autosummary",
36+
"sphinx.ext.inheritance_diagram",
37+
"sphinx.ext.intersphinx",
38+
"sphinx.ext.todo",
39+
"myst_parser",
40+
]
41+
42+
# Add any paths that contain templates here, relative to this directory
43+
templates_path = ["_templates"]
44+
45+
# Template configuration
46+
autosummary_generate = True
47+
add_module_names = False
48+
autodoc_typehints = "description"
49+
autodoc_preserve_defaults = True
50+
51+
52+
# List of patterns to ignore when looking for source files
53+
exclude_patterns = [
54+
"_build",
55+
"Thumbs.db",
56+
".DS_Store",
57+
"**/generated/**",
58+
"**/tests/**",
59+
"**/__pycache__/**",
60+
"**/.pytest_cache/**",
61+
"**/.mypy_cache/**",
62+
"**/.ruff_cache/**",
63+
]
64+
65+
# The theme to use for HTML and HTML Help pages
66+
html_theme = "furo"
67+
68+
# Theme options
69+
html_theme_options = {
70+
"sidebar_hide_name": False,
71+
"navigation_with_keys": True,
72+
"source_repository": "https://github.com/crispthinking/athena-protobufs/",
73+
"source_branch": "main",
74+
"source_directory": "docs/",
75+
"light_css_variables": {
76+
"color-sidebar-background": "#f8f9fb",
77+
"color-brand-primary": "#20539E",
78+
"color-brand-content": "#20539E",
79+
"color-foreground-primary": "#4E585F",
80+
"color-background-primary": "#FEFEFE",
81+
"color-background-secondary": "#F7F7F7",
82+
"font-stack": (
83+
"'Nunito Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', "
84+
"Helvetica, Arial, sans-serif"
85+
),
86+
},
87+
"dark_css_variables": {
88+
"color-brand-primary": "#B6CBE9",
89+
"color-brand-content": "#B6CBE9",
90+
"color-foreground-primary": "#D5D5D5",
91+
"color-background-primary": "#393939",
92+
"color-background-secondary": "#434343",
93+
"color-sidebar-background": "#1E1E1E",
94+
"font-stack": (
95+
"'Nunito Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', "
96+
"Helvetica, Arial, sans-serif"
97+
),
98+
},
99+
"light_logo": "images/logo/Resolver_Lettermark_Main.png",
100+
"dark_logo": "images/logo/Resolver_Lettermark_White.png",
101+
}
102+
103+
# HTML configuration
104+
html_static_path = ["_static"]
105+
html_favicon = "_static/images/favicon/favicon-32x32.png"
106+
html_css_files = ["css/custom.css"]
107+
108+
# HTML context
109+
html_context = {
110+
"display_github": True,
111+
"github_user": "crispthinking",
112+
"github_repo": "athena-protobufs",
113+
"github_version": "main",
114+
"conf_py_path": "/docs/",
115+
}
116+
117+
# Intersphinx configuration
118+
intersphinx_mapping = {
119+
"python": ("https://docs.python.org/3", None),
120+
"grpc": ("https://grpc.github.io/grpc/python/", None),
121+
}
122+
123+
# Create required directories if they don't exist
124+
for path in ["_static", "_templates/autosummary"]:
125+
path_obj = Path(path)
126+
path_obj.mkdir(parents=True, exist_ok=True)
127+
128+
# MyST parser configuration
129+
myst_enable_extensions = [
130+
"deflist",
131+
"tasklist",
132+
"colon_fence",
133+
]
134+
135+
# Napoleon settings
136+
napoleon_google_docstring = True
137+
napoleon_numpy_docstring = True
138+
napoleon_include_init_with_doc = True
139+
napoleon_include_private_with_doc = False
140+
napoleon_include_special_with_doc = True
141+
napoleon_use_admonition_for_examples = True
142+
napoleon_use_admonition_for_notes = True
143+
napoleon_use_admonition_for_references = True
144+
napoleon_use_ivar = False
145+
napoleon_use_param = True
146+
napoleon_use_rtype = True
147+
napoleon_type_aliases = None
148+
149+
# AutoDoc settings
150+
autodoc_default_options = {
151+
"members": True,
152+
"member-order": "bysource",
153+
"special-members": "__init__",
154+
"undoc-members": True,
155+
"exclude-members": "__weakref__",
156+
"show-inheritance": True,
157+
}
158+
159+
# Todo extension
160+
todo_include_todos = True
161+
162+
# Output file name
163+
htmlhelp_basename = "AthenaProtobufsdoc"

‎docs/index.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. Athena Classifier NodeJS SDK documentation master file, created by
2+
sphinx-quickstart on Thu Aug 28 15:47:19 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Athena Classifier NodeJS SDK documentation
7+
==========================================
8+
9+
Add your content using ``reStructuredText`` syntax. See the
10+
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
11+
documentation for details.
12+
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
:caption: Contents:
17+

0 commit comments

Comments
 (0)