Initial ReadTheDocs Setup

.gitignore

@@ -6,4 +6,11 @@
 build/
 *.swp
 doxygen-docs/
+docs/_build/
+docs/api/generated/
+docs/api/reference/
+docs/examples/generated/
+docs/generated/
+docs/models/generated/
+docs/xml/
 __pycache__

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - doxygen
+    - graphviz
+  jobs:
+    pre_build:
+      - python docs/generate_model_docs.py
+      - cd docs && doxygen Doxyfile
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Added 3, 10, 37, and 39 bus test cases.
 - Updated documentation.
+- Added support for Read the Docs
 - Added JSON parsing.
 - Automatic differentiation with enzyme (w.r.t. internal and external variables).
 - Added PR and issue templates.

docs/Doxyfile

@@ -0,0 +1,17 @@
+PROJECT_NAME = "GridKit"
+OUTPUT_DIRECTORY = .
+
+INPUT = ../GridKit
+RECURSIVE = YES
+EXCLUDE_PATTERNS = *.md
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = ..
+
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_XML = YES
+XML_OUTPUT = xml
+XML_PROGRAMLISTING = NO
+
+EXTRACT_ALL = YES
+QUIET = YES

docs/README.md

@@ -1,32 +1,39 @@
-# GridKit Documentation Target
+# GridKit Documentation
 
-We use CMake's built-in `FindDoxygen` module to generate a target that will
-use Doxygen to build the project documentation.
+GridKit documentation can be built two ways:
 
-## Building
+1. Read the Docs builds the Sphinx site from `docs/conf.py`.
+2. CMake can build the existing Doxygen HTML target.
+
+## Read the Docs Build
+
+The Read the Docs proof of concept is configured by `.readthedocs.yaml`.
+Before Sphinx runs, the build generates Markdown wrapper pages and Doxygen XML:
 
-The documentation target is excluded from the default set of targets built via
-`make` (or `cmake --build .`). It must be designated explicitly with
 ```sh
-make GridKitDocs
+python docs/generate_model_docs.py
+cd docs && doxygen Doxyfile
 ```
-or
+
+To test the same flow locally:
+
 ```sh
-cmake --build . -t GridKitDocs
+python -m pip install -r docs/requirements.txt
+python docs/generate_model_docs.py
+cd docs && doxygen Doxyfile
+cd ..
+sphinx-build -T -b html docs docs/_build/html
 ```
-The generated files can be found in the build directory under `docs/html/` and
-the main page is `docs/html/index.html`.
-
-If you wish to inspect the Doxyfile itself, it is generated as
-`docs/Doxyfile.GridKitDocs`.
-
-## Notes
-The reasoning behind taking this approach is as follows:
-
-1. It is easier to maintain just the few options we need to customize rather
-   than a whole Doxyfile (leave what can be generated out of the repo); if
-   another option is needed, it's easy to look it up.
-2. Since the documentation can be seen as a "product" or "artifact" of the code,
-   it makes sense for it to be a buildable "target"
-3. Generated files should not be placed in the source directory. The binary
-   directory makes sense for this, and the CMake target makes this easy.
+
+The generated Sphinx files, Doxygen XML, and HTML output are build artifacts and
+should not be committed.
+
+## CMake Doxygen Target
+
+The existing CMake target is still available for standalone Doxygen HTML output:
+
+```sh
+cmake --build build -t GridKitDocs
+```
+
+The generated files are written under the build directory.

docs/api.md

@@ -0,0 +1,35 @@
+# API Reference
+
+```{toctree}
+:maxdepth: 1
+:titlesonly:
+:hidden:
+
+GridKit Core <api/reference/namespace_GridKit>
+Solvers <api/reference/namespace_AnalysisManager>
+Phasor Dynamics <api/reference/namespace_GridKit__PhasorDynamics>
+Power Electronics <api/reference/namespace_GridKit__PowerElectronics>
+Power Flow Data <api/reference/namespace_GridKit__PowerFlowData>
+Linear Algebra <api/reference/namespace_GridKit__LinearAlgebra>
+Math Utilities <api/reference/namespace_GridKit__Math>
+Model Utilities <api/reference/namespace_GridKit__Model>
+Utilities <api/reference/namespace_GridKit__Utilities>
+Testing <api/reference/namespace_GridKit__Testing>
+```
+
+The API reference is organized by the primary GridKit namespaces. Lower-level
+class, struct, enum, function, and file pages are generated by Exhale and linked
+from these namespace pages.
+
+## Main Areas
+
+- [GridKit core](api/reference/namespace_GridKit.rst)
+- [Solvers](api/reference/namespace_AnalysisManager.rst)
+- [GridKit::PhasorDynamics](api/reference/namespace_GridKit__PhasorDynamics.rst)
+- [GridKit::PowerElectronics](api/reference/namespace_GridKit__PowerElectronics.rst)
+- [GridKit::PowerFlowData](api/reference/namespace_GridKit__PowerFlowData.rst)
+- [GridKit::LinearAlgebra](api/reference/namespace_GridKit__LinearAlgebra.rst)
+- [GridKit::Model](api/reference/namespace_GridKit__Model.rst)
+- [GridKit::Math](api/reference/namespace_GridKit__Math.rst)
+- [GridKit::Utilities](api/reference/namespace_GridKit__Utilities.rst)
+- [GridKit::Testing](api/reference/namespace_GridKit__Testing.rst)

docs/applications/index.md

@@ -0,0 +1,15 @@
+# Applications
+
+```{toctree}
+:maxdepth: 2
+:titlesonly:
+:hidden:
+
+../generated/application-input-format
+```
+
+## PhasorDynamics
+
+- [Application Input Format](../generated/application-input-format.md)
+- `application/PhasorDynamics/DynamicSimulation.cpp`
+- `application/PhasorDynamics/ContingencyAnalysis.cpp`

docs/conf.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+
+from exhale import utils as exhale_utils
+
+project = "GridKit"
+author = "GridKit Developers"
+
+docs_dir = Path(__file__).parent.resolve()
+
+extensions = ["breathe", "exhale", "myst_parser", "sphinx.ext.graphviz"]
+
+breathe_projects = {"GridKit": str(docs_dir / "xml")}
+breathe_default_project = "GridKit"
+
+
+def exhale_specs(kind):
+    if kind in {"class", "struct"}:
+        return [":members:"]
+    return []
+
+
+exhale_args = {
+    "containmentFolder": "./api/reference",
+    "rootFileName": "EXCLUDE",
+    "doxygenStripFromPath": str(docs_dir.parent),
+    "createTreeView": False,
+    "customSpecificationsMapping": exhale_utils.makeCustomSpecificationsMapping(
+        exhale_specs
+    ),
+    "contentsDirectives": False,
+    "fullToctreeMaxDepth": 1,
+    "pageLevelConfigMeta": ":orphan:",
+}
+
+primary_domain = "cpp"
+
+html_theme = "sphinx_rtd_theme"
+html_extra_path = ["Figures"]
+html_theme_options = {
+    "collapse_navigation": False,
+    "navigation_depth": 6,
+    "titles_only": True,
+}
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+myst_enable_extensions = [
+    "amsmath",
+    "dollarmath",
+    "html_image",
+]
+myst_heading_anchors = 5
+
+exclude_patterns = [
+    "_build",
+    "api/generated/**",
+    "xml",
+    "README.md",
+    "superpowers/**",
+]

docs/development/index.md

@@ -0,0 +1,19 @@
+# Development
+
+```{toctree}
+:maxdepth: 2
+:titlesonly:
+:hidden:
+
+../generated/contributing
+../generated/buildsystem
+../generated/documentation-build
+../generated/changelog
+```
+
+## Sections
+
+- [Contributing](../generated/contributing.md)
+- [Buildsystem](../generated/buildsystem.md)
+- [Documentation Build](../generated/documentation-build.md)
+- [Changelog](../generated/changelog.md)