Add Sphinx Docs

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
 
 # PyBuilder
 .pybuilder/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+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
+
+# 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)

docs/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api.rst

@@ -0,0 +1,10 @@
+===============
+ API Reference
+===============
+
+.. autosummary::
+   :toctree: generated
+   :template: custom-module-template.rst
+   :recursive:
+
+   zdPlasmaPy

docs/conf.py

@@ -0,0 +1,90 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "zdPlasmaPy"
+# copyright = "YEAR, AUTHOR"
+# author = ""
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx_autodoc_typehints",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Numpy-doc config
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_attr_annotations = True
+napoleon_preprocess_types = True
+
+# Enable numbered references
+numfig = True
+
+autodoc_type_aliases = {
+    "NDArray": "numpy.typing.NDArray",
+    "ArrayLike": "numpy.typing.ArrayLike",
+}
+
+napoleon_type_aliases = {
+    "ndarray": "numpy.typing.NDArray",
+}
+
+autodoc_default_options = {"ignore-module-all": True}
+autodoc_typehints = "description"
+# autodoc_class_signature = "mixed"
+
+# The default role for text marked up `like this`
+default_role = "any"
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = "py"
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = "python"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_book_theme"
+html_static_path = ["_static"]
+
+html_theme_options = {
+    "github_url": "https://github.com/mjimenez-arch/zdPlasmaPyCourse",
+}
+
+pygments_style = "sphinx"
+
+# -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+}
+
+nitpick_ignore = {
+    ("py:class", "numpy.typing.ArrayLike"),
+    ("py:class", "numpy.typing.NDArray"),
+    ("py:class", "numpy.typing.Scalar"),
+}
+nitpick_ignore_regex = {
+    ("py:class", r".*_ScalarT"),
+}

docs/index.rst

@@ -0,0 +1,12 @@
+.. zdPlasmaPyCourse documentation master file
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+zdPlasmaPy documentation
+========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   API Reference <api>

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

pyproject.toml

@@ -1,6 +1,28 @@
 [project]
 name = "zdPlasmaPy"
 version = "0.1.0"
+dependencies = [
+    "h5py>=3.16.0",
+    "ipykernel>=7.3.0",
+    "jsonschema>=4.26.0",
+    "matplotlib>=3.11.0",
+    "numpy<2.0.0",
+    "pytest>=9.1.0",
+    "pyyaml>=6.0.3",
+    "scipy>=1.17.1",
+    "streamlit>=1.58.0",
+]
+
+[project.optional-dependencies]
+docs = [
+    "sphinx>=7,<10",
+    "sphinx_autodoc_typehints>=1.19",
+    "sphinx-book-theme~=1.2.0",
+    "myst_parser>=0.14.0",
+]
+dev = [
+    "ruff>=0.15.17",
+]
 
 [project.scripts]
 zdplasmapy = "main:main"
@@ -11,7 +33,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
 py-modules = ["main"]
+package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
-where = ["."]
-include = ["src*"]
+where = ["src"]

src/eedf_solver.py → src/zdPlasmaPy/eedf_solver.py

@@ -59,9 +59,9 @@ def _detect_loki_binary(explicit_path: Optional[str]) -> Optional[str]:
     if explicit_path and os.path.isfile(explicit_path) and os.access(explicit_path, os.X_OK):
         return explicit_path
     candidates = [
-        os.path.join(os.path.dirname(__file__), "..", "external", "LoKI-B-cpp", "build", "app", "loki"),
-        os.path.join(os.path.dirname(__file__), "..", "external", "LoKI-B-cpp", "build", "loki"),
-        os.path.join(os.path.dirname(__file__), "..", "external", "LoKI-B-cpp", "build", "bin", "loki"),
+        os.path.join(os.path.dirname(__file__), "..", "..", "external", "LoKI-B-cpp", "build", "app", "loki"),
+        os.path.join(os.path.dirname(__file__), "..", "..", "external", "LoKI-B-cpp", "build", "loki"),
+        os.path.join(os.path.dirname(__file__), "..", "..", "external", "LoKI-B-cpp", "build", "bin", "loki"),
     ]
     for p in candidates:
         p = os.path.abspath(p)

src/util.py → src/zdPlasmaPy/util.py

@@ -1,9 +1,9 @@
 import importlib.util
 import os
-from src.config_parser import load_config
-from src.chemistry_parser import load_chemistry
-from src.transport_models import DECLARATIONS_FUNCS
-from src.case_utils import group_parameters
+from .config_parser import load_config
+from .chemistry_parser import load_chemistry
+from .transport_models import DECLARATIONS_FUNCS
+from .case_utils import group_parameters
 
 def build_model_definition(config_path):
     """

tests/test_chemistry_parser_security.py

@@ -1,7 +1,7 @@
 import unittest
 import math
 
-from src.chemistry_parser import build_lambda as _build_lambda
+from zdPlasmaPy.chemistry_parser import build_lambda as _build_lambda
 
 
 class TestChemistryParserSecurity(unittest.TestCase):

tests/test_core_functionality.py

@@ -1,6 +1,6 @@
 import unittest
 import os
-from src.config_parser import load_config
+from zdPlasmaPy.config_parser import load_config
 
 class TestConfigParser(unittest.TestCase):
     def setUp(self):

tests/test_eedf_solver.py

@@ -16,7 +16,7 @@
 import unittest
 import numpy as np
 
-from src.eedf_solver import LokiBSolver
+from zdPlasmaPy.eedf_solver import LokiBSolver
 
 FAKE_SOLVER_CODE = r"""#!/usr/bin/env python3
 import sys, json, math

tests/test_loki_input_gen.py

@@ -7,7 +7,7 @@
 # Add project root to path
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
 
-from src.eedf_solver import _build_loki_input
+from zdPlasmaPy.eedf_solver import _build_loki_input
 
 class TestLokiInputGeneration(unittest.TestCase):
     def test_pass_through_parameters(self):

tests/test_loki_integration.py

@@ -8,7 +8,7 @@
 # Ensure src is in path
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
 
-from src.eedf_solver import run_eedf, _detect_loki_binary
+from zdPlasmaPy.eedf_solver import run_eedf, _detect_loki_binary
 
 class TestLokiIntegration(unittest.TestCase):
     def setUp(self):