Merge pull request #5 from aetherspritee/gemini

Gemini Refactor

Author: arunoruto

.github/workflows/docs.yml

@@ -0,0 +1,22 @@
+name: "Build docs"
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "docs/**/*"
+      - ".github/workflows/docs.yml"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: sphinx-notes/pages@v3
+        with:
+          documentation_path: ./docs/source

.gitignore

@@ -1,5 +1,6 @@
 .envrc
 .direnv
+RESULTS/
 
 *.csv
 

README.md

@@ -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     = source
+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/Makefile

@@ -0,0 +1,8 @@
+furo
+myst-parser
+sphinx-autoapi
+sphinx-autodoc-typehints
+sphinx-copybutton
+sphinx
+sphinxcontrib-bibtex
+sphinxcontrib-napoleon

docs/requirements.txt

@@ -0,0 +1,132 @@
+import os
+import sys
+
+from pyfracval import __version__, _authors
+
+# Adjust the path to go up two levels from docs/source/ to the project root
+sys.path.insert(0, os.path.abspath("../../"))
+
+# 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 = name = "PyFracVAL"
+author = _authors
+copyright = f"2025, {_authors}"
+version, release = __version__, __version__.split("+")[0]
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.napoleon",  # Support for NumPy and Google style docstrings
+    "sphinx.ext.autodoc",  # Core Sphinx library to pull documentation from docstrings
+    "sphinx.ext.intersphinx",  # Link to other projects' documentation (e.g. Python, NumPy)
+    "sphinx.ext.viewcode",  # Add links to source code
+    "sphinx_autodoc_typehints",  # Automatically document types based on type hints
+    "autoapi.extension",
+    "myst_parser",  # Parse Markdown files
+    "sphinx_copybutton",  # Add copy buttons to code blocks
+    "sphinxcontrib.bibtex",  # For BibTeX citation support
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+myst_enable_extensions = [
+    "colon_fence",  # Enables ::: directives for admonitions, etc.
+    "deflist",  # Enables definition lists
+    "linkify",  # Auto-detect URLs and make them links (use with caution)
+    "tasklist",  # Enable checklists - [ ] / - [x]
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html_theme = "alabaster"
+# html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
+# html_logo = "_static/logo.png" # Optional: Add a logo file to _static/
+# html_favicon = "_static/favicon.ico" # Optional: Add a favicon
+html_static_path = ["_static"]
+
+# Napoleon config
+# napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False  # Include __init__ docstrings
+napoleon_include_private_with_doc = False  # Usually False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+# napoleon_use_ivar = False
+# napoleon_use_param = True
+# napoleon_use_rtype = True
+napoleon_preprocess_types = False  # Let sphinx-autodoc-typehints handle types
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# autodoc
+autoclass_content = "class"
+autodoc_typehints = "none"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+inheritance_alias = {}
+
+# autoapi
+autoapi_dirs = ["../../pyfracval"]
+autoapi_options = [
+    "members",
+    # "undoc-members",
+    # "private-members",
+    # "show-inheritance",
+    # "show-module-summary",
+    # "special-members",  # '__init__' etc.
+    "imported-members",
+]
+autoapi_ignore = ["*migrations*", "__init__*"]
+autoapi_add_toctree_entry = True
+
+## Use sphinx-autodoc-typehints setup
+# Add parameter types from Napoleon processing
+always_document_param_types = True
+# Show short names for types (e.g. ndarray instead of numpy.ndarray)
+typehints_fully_qualified = False
+# Process return type hints
+typehints_document_rtype = True
+# Don't use napoleon rtype processing, let extension handle it
+# typehints_use_rtype = False
+# Show default values after comma, 'braces' is other option
+# typehints_defaults = "comma"
+# Optional: Simplify representation of complex types like Union[str, Path]
+# typehints_formatter = lambda annotation, config: repr(annotation)
+always_use_bars_union = True
+
+## BibTeX Configuration: Tell the extension where your .bib file is:
+bibtex_bibfiles = ["references.bib"]  # Assumes references.bib is in docs/source/
+bibtex_default_style = "unsrt"  # Common numeric style, others: plain, alpha
+# Optional: Control how citations look, e.g. [(Morán et al. 2019)]
+bibtex_reference_style = "author_year"
+
+## Intersphinx Configuration: Set up links to external documentation:
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pytest": ("https://docs.pytest.org/en/stable/", None),
+    # Add others like scipy, pandas if you use/reference them
+}

docs/source/_static/logo.png

@@ -0,0 +1,14 @@
+# Welcome to pyfracval's documentation!
+
+<img src="_static/logo.png" alt="PyFracVAL Logo" width="50%">
+
+PyFracVAL generates fractal-like aggregates... (add a brief description)
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents:
+
+installation
+usage
+references
+```

docs/source/conf.py

@@ -0,0 +1,65 @@
+# Installation
+
+This page provides instructions on how to install the `pyfracval` package.
+
+## Prerequisites
+
+- Python 3.10 or higher (check your version with `python --version`).
+- `pip` (Python package installer)
+
+## Standard Installation
+
+The recommended way to install `pyfracval` is using `pip` from the Python Package Index (PyPI) (once you publish it there):
+
+```bash
+pip install pyfracval
+```
+
+This will install the package and its required dependencies (like NumPy, Pydantic, etc.).
+
+## Installation from Source (for Development)
+
+If you want to contribute to the project or install the latest development version directly from the source code (e.g., after cloning from GitHub), follow these steps:
+
+1.  **Clone the Repository:**
+
+    ```bash
+    git clone https://github.com/your-username/pyfracval.git
+    cd pyfracval
+    ```
+
+    _(Replace with your actual repository URL)_
+
+2.  **Create a Virtual Environment (Recommended):**
+    It's highly recommended to use a virtual environment to manage dependencies:
+
+    ```bash
+    # Using venv (built-in)
+    python -m venv .venv
+    source .venv/bin/activate # On Linux/macOS
+    # .\venv\Scripts\activate # On Windows
+
+    # Or using conda
+    # conda create -n pyfracval-env python=3.11 # Or your preferred version
+    # conda activate pyfracval-env
+    ```
+
+3.  **Install in Editable Mode:**
+    Installing in editable mode (`-e`) links the installed package to your source code, so changes you make are immediately reflected without reinstalling.
+    ```bash
+    pip install -e .[dev,test,docs]
+    ```
+    - The `.` refers to the current directory (where `pyproject.toml` is).
+    - The `[dev,test,docs]` part installs optional dependencies needed for development, running tests, and building documentation (assuming you define these groups in your `pyproject.toml`). Adjust or remove this part as needed. If you don't have groups defined, you might just do `pip install -e .` and install dev tools separately.
+
+## Checking the Installation
+
+You can verify the installation by importing the package in a Python interpreter:
+
+```python
+import pyfracval
+# Optional: check version if you have defined __version__
+# print(pyfracval.__version__)
+```
+
+If no errors occur, the installation was successful.

docs/source/index.md

@@ -0,0 +1,23 @@
+@article{Moran2019FracVAL,
+	author = {J. Morán and A. Fuentes and F. Liu and J. Yon},
+	title = {{FracVAL: An improved tunable algorithm of cluster-cluster
+	         aggregation for generation of fractal structures formed by
+	         polydisperse primary particles}},
+	journal = {Computer Physics Communications},
+	year = {2019},
+	volume = {239},
+	pages = {225--237},
+	doi = {10.1016/j.cpc.2019.01.015},
+}
+
+@article{Filippov2000Tunable,
+	author = {Filippov, A. V. and Zurita, M. and Rosner, D. E.},
+	title = {{Fractal-like Aggregates: Relation between Morphology and Physical
+	         Properties}},
+	journal = {Journal of Colloid and Interface Science},
+	year = {2000},
+	volume = {229},
+	number = {1},
+	pages = {261--273},
+	doi = {10.1006/jcis.2000.7027},
+}