Merge pull request #73 from alchem0x2A/master

add auto apidoc to documentation html

.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

.gitignore

@@ -787,3 +787,4 @@ examples/ex1-ase/
 /paper/paper.pdf
 /paper/jats/
 /doc/_build/
+/doc/api/

doc/Makefile

@@ -5,16 +5,29 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
+SPHINXDOC     ?= sphinx-apidoc
 SOURCEDIR     = .
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 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)

doc/conf.py

@@ -8,20 +8,26 @@
 
 project = "SPARC-X-API"
 copyright = "2024, SPARC-X Developmers"
-author = "Tian Tian"
+author = "Tian Tian, Lucas R Timmerman, Ben Comer"
 
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 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

doc/package_components.md

@@ -1 +1,8 @@
 # SPARC-X-API Package Components
+
+
+```{toctree}
+:maxdepth: 4
+
+api/modules.rst
+```