From c2d95601cc346b0a813c2b9e566fbf2a9a273d24 Mon Sep 17 00:00:00 2001
From: "T.Tian" <alchem0x2a@gmail.com>
Date: Tue, 19 Nov 2024 17:58:24 +0800
Subject: [PATCH 1/2] allow using makefile for doc build

---
 doc/Makefile              | 15 ++++++++++++++-
 doc/conf.py               | 11 ++++++++++-
 doc/package_components.md |  7 +++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index d4bb2cbb..02a1d6a3 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,6 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
+SPHINXDOC     ?= sphinx-apidoc
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -12,9 +13,21 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+# Build the api doc --> doc/api/modules.rst
+apidoc:
+	@$(SPHINXDOC) -f -e -M -o "$(SOURCEDIR)"/api "$(SOURCEDIR)"/../sparc
+
+
+.PHONY: help Makefile apidoc
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html: apidoc
+
+# Reuse the make clean rule from sphinx and remove api/
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(SOURCEDIR)"/api $(SPHINXOPTS) $(O)
diff --git a/doc/conf.py b/doc/conf.py
index 1e3685d3..34bf6b14 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -8,7 +8,7 @@
 
 project = "SPARC-X-API"
 copyright = "2024, SPARC-X Developmers"
-author = "Tian Tian"
+author = "Tian Tian, Lucas R Timmerman, Ben Comer"
 
 
 # -- General configuration ---------------------------------------------------
@@ -16,12 +16,18 @@
 
 extensions = [
     "sphinx.ext.githubpages",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",  # For Google/NumPy style docstrings
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",  # Adds links to source code
     "myst_parser",
 ]
 
 source_suffix = {
     ".md": "markdown",
     ".txt": "markdown",
+    ".rst": "restructuredtext",
 }
 
 templates_path = ["_templates"]
@@ -44,3 +50,6 @@
 myst_enable_extensions = [
     "html_admonition",
 ]
+
+coverage_Show_missing_items = True
+autosummary_generate = True
diff --git a/doc/package_components.md b/doc/package_components.md
index 0ae1726e..50a3e81d 100644
--- a/doc/package_components.md
+++ b/doc/package_components.md
@@ -1 +1,8 @@
 # SPARC-X-API Package Components
+
+
+```{toctree}
+:maxdepth: 4
+
+api/modules.rst
+```

From bdc76aed344549a85d8f79b9760aaecad3b812b4 Mon Sep 17 00:00:00 2001
From: "T.Tian" <alchem0x2a@gmail.com>
Date: Tue, 19 Nov 2024 18:01:26 +0800
Subject: [PATCH 2/2] ignore api subfolder

---
 .github/workflows/publish_doc_pages.yml | 11 ++++++++---
 .gitignore                              |  1 +
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/publish_doc_pages.yml b/.github/workflows/publish_doc_pages.yml
index 8b2eab4f..4c43f87c 100644
--- a/.github/workflows/publish_doc_pages.yml
+++ b/.github/workflows/publish_doc_pages.yml
@@ -1,15 +1,18 @@
 name: Publish Document Pages for SPARC-X-API
 
+# SPARC source code components are also parsed at each submission
 on:
   push:
     branches:
       - master
       - 'doc/**'
+      - 'sparc/**'
   pull_request:
     branches:
       - master
     paths:
       - 'doc/**'
+      - 'sparc/**'
 
   workflow_dispatch:
 
@@ -34,17 +37,19 @@ jobs:
         pip install -e ".[doc]"
     - name: Build sphix doc
       run: |
-        sphinx-build doc doc/_build
+        # sphinx-build doc doc/_build
+        cd doc
+        make clean && make html
     - name: Deploy to github pages
       uses: peaceiris/actions-gh-pages@v4
       if: github.ref == 'refs/heads/master' && github.event_name == 'push'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_branch: gh_pages
-        publish_dir: doc/_build
+        publish_dir: doc/_build/html
     - name: Upload preview when creating pull request
       if: github.event_name == 'pull_request'
       uses: actions/upload-artifact@v3
       with:
         name: docs_build_preview
-        path: doc/_build
+        path: doc/_build/html
diff --git a/.gitignore b/.gitignore
index 2e6415d1..b59d4ed3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -787,3 +787,4 @@ examples/ex1-ase/
 /paper/paper.pdf
 /paper/jats/
 /doc/_build/
+/doc/api/