Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API Documentation with Sphinx #75

Merged
merged 59 commits into from
Aug 24, 2024
Merged
Show file tree
Hide file tree
Changes from 58 commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
f2aca2e
adding pydocstyle to pyproject.toml
adamamer20 Aug 21, 2024
a1bbebd
adding mesa_frames __init__ docstring
adamamer20 Aug 21, 2024
85c702d
adding mesa_frames/abstract __init__ docstring
adamamer20 Aug 21, 2024
45b1dfd
fixing mesa_frames/abstract/agents.py for ruff.pydocstyle
adamamer20 Aug 21, 2024
91ee44b
fixing mesa_frames/abstract/mixin.py for ruff.pydocstyle
adamamer20 Aug 21, 2024
aff9b52
fixing mesa_frames/abstract/space.py for ruff.pydocstyle
adamamer20 Aug 21, 2024
c6c8896
adding __init__ to mesa_frames/concrete
adamamer20 Aug 22, 2024
ccf02fc
fixing arguments in __init__ of the module
adamamer20 Aug 22, 2024
31e5d67
fixing mesa_frames/concrete/model.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
14d2482
fixing mesa_frames/concrete/agents.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
43770d6
fixing mesa_frames/concrete/pandas/agentset.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
55c6f91
adding __init__ to mesa_frames/concrete/pandas
adamamer20 Aug 22, 2024
b1850f5
fixing mesa_frames/concrete/pandas/mixin.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
923caf3
removing methods section (hard to mantain, and automatically generate…
adamamer20 Aug 22, 2024
6c8af78
removing properties (sphinx will generate that)
adamamer20 Aug 22, 2024
3455d5d
moving parameters to __init__
adamamer20 Aug 22, 2024
3834e67
fixing mesa_frames/concrete/pandas/space.py
adamamer20 Aug 22, 2024
3f41bf2
adding __init__ to mesa_frames/concrete/polars
adamamer20 Aug 22, 2024
92e3dad
removing docstring (sphinx will autogenerate from AgentSetDF)
adamamer20 Aug 22, 2024
ae3cd15
removing docstring (sphinx will autogenerate from GridDF)
adamamer20 Aug 22, 2024
e904e01
removing docstring (sphinx will autogenerate from DFMixin)
adamamer20 Aug 22, 2024
283a996
deactivate D101 and D102 (too many errors due to inheritance)
adamamer20 Aug 22, 2024
d135d62
deactivating d105 (doesn't work well with inheritance)
adamamer20 Aug 22, 2024
09ca47f
fixing mesa_frames/concrete/polars/agentset.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
1e32f46
fixing mesa_frames/concrete/polars/mixin.py for ruff.pydocstyle
adamamer20 Aug 22, 2024
ebfa347
fixing mesa_frames/concrete/polars/space.py
adamamer20 Aug 22, 2024
d1b2acf
ignoring in tests, examples or docs
adamamer20 Aug 22, 2024
e5af36b
test -> tests
adamamer20 Aug 22, 2024
d057c39
adding __init__ to type aliases
adamamer20 Aug 22, 2024
ce8aaf1
removing commented test
adamamer20 Aug 22, 2024
cf9cbe1
test fix
adamamer20 Aug 22, 2024
f082224
adding sphinx dependencies
adamamer20 Aug 22, 2024
6e4ee83
quick starting sphinx
adamamer20 Aug 22, 2024
8d1c100
updating dependencies for docs
adamamer20 Aug 22, 2024
d4c5094
adding required dependencies
adamamer20 Aug 24, 2024
51f4b38
configuring api documentation
adamamer20 Aug 24, 2024
9453a37
creating docs structure
adamamer20 Aug 24, 2024
4e1d0a8
copying description from parent class for abstract classes
adamamer20 Aug 24, 2024
ac8a74b
renaming docs action to mkdocs
adamamer20 Aug 24, 2024
55dbb89
changing requirements to mkdocs_requirements.txt
adamamer20 Aug 24, 2024
4b1ee16
moving mkdocs to docs/general
adamamer20 Aug 24, 2024
1401ad3
unique gh action for deployment
adamamer20 Aug 24, 2024
53bbede
adding sphinx files to docs/api
adamamer20 Aug 24, 2024
fae5822
fix: checkout = false (checked out before)
adamamer20 Aug 24, 2024
22d2c2f
fix: unique gh pages actions
adamamer20 Aug 24, 2024
d63902b
fix: removed api from docs
adamamer20 Aug 24, 2024
f8945d6
rename for clarity
adamamer20 Aug 24, 2024
58ebd14
removed redundant/useless requirements
adamamer20 Aug 24, 2024
9d6d450
moving to /reference for clarity (similar to polars)
adamamer20 Aug 24, 2024
dba7fd8
fix: update reqs
adamamer20 Aug 24, 2024
fa1b20d
adding section headers
adamamer20 Aug 24, 2024
61c9efa
removing properties (automatically generated by sphinx)
adamamer20 Aug 24, 2024
1fbbe6a
Revert "adding section headers"
adamamer20 Aug 24, 2024
e4dd017
adding title
adamamer20 Aug 24, 2024
2dae685
adding description for backend specific classes (better for sphinx)
adamamer20 Aug 24, 2024
f380206
Merge branch 'main' of https://github.com/adamamer20/mesa-frames into…
adamamer20 Aug 24, 2024
3b8f89a
run only 72-api-documentation-with-sphinx
adamamer20 Aug 24, 2024
0a8f864
Merge branch 'main' into 72-api-documentation-with-sphinx
adamamer20 Aug 24, 2024
8724b20
changing branch to main
adamamer20 Aug 24, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 31 additions & 11 deletions .github/workflows/docs-gh-pages.yml
Original file line number Diff line number Diff line change
@@ -1,19 +1,39 @@
name: Publish docs via GitHub Pages
name: Build and Deploy Documentation

on:
push:
branches:
- main
# - main
- 72-api-documentation-with-sphinx

jobs:
build:
name: Deploy docs
build-and-deploy-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v2
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for .git-restore-mtime to work correctly

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install .[docs]

- name: Build MkDocs site (general documentation)
run: mkdocs build --config-file mkdocs.yml --site-dir ./site
rht marked this conversation as resolved.
Show resolved Hide resolved

- name: Build Sphinx docs (api documentation)
run: |
sphinx-build -b html docs/api site/api

- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REQUIREMENTS: docs/requirements.txt
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site
force_orphan: true
20 changes: 20 additions & 0 deletions docs/api/Makefile
Original file line number Diff line number Diff line change
@@ -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)
77 changes: 77 additions & 0 deletions docs/api/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
import os

# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here.
import sys
from pathlib import Path

sys.path.insert(0, str(Path("..").resolve()))

# -- Project information -----------------------------------------------------
project = "mesa-frames"
author = "Adam Amer"
copyright = f"2023, {author}"

# -- General configuration ---------------------------------------------------
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx.ext.intersphinx",
"numpydoc",
"sphinx_copybutton",
"sphinx_design",
"autodocsumm",
]

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# -- Options for HTML output -------------------------------------------------
html_theme = "pydata_sphinx_theme"
html_static_path = ["_static"]
html_show_sourcelink = False

# -- Extension settings ------------------------------------------------------
# intersphinx mapping
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"numpy": ("https://numpy.org/doc/stable/", None),
"pandas": ("https://pandas.pydata.org/docs/", None),
"polars": ("https://pola-rs.github.io/polars/py-polars/html/", None),
}

# numpydoc settings
numpydoc_show_class_members = False

# Copybutton settings
copybutton_prompt_text = r">>> |\.\.\. "
copybutton_prompt_is_regexp = True

# -- Custom configurations ---------------------------------------------------
autoclass_content = "class"
autodoc_member_order = "bysource"
autodoc_default_options = {"special-members": True, "exclude-members": "__weakref__"}

# -- GitHub link and user guide settings -------------------------------------
github_root = "https://github.com/adamamer20/mesa-frames"
web_root = "https://adamamer20.github.io/mesa-frames"

html_theme_options = {
"external_links": [
{
"name": "User guide",
"url": f"{web_root}/user-guide/",
},
],
"icon_links": [
{
"name": "GitHub",
"url": github_root,
"icon": "fa-brands fa-github",
},
],
"navbar_end": ["navbar-icon-links"],
}
27 changes: 27 additions & 0 deletions docs/api/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
mesa-frames API
===============

This page provides a high-level overview of all public mesa-frames objects, functions, and methods. All classes and functions exposed in the ``mesa_frames.*`` namespace are public.

.. grid::

.. grid-item-card::

.. toctree::
:maxdepth: 2

reference/agents/index

.. grid-item-card::

.. toctree::
:maxdepth: 1

reference/model

.. grid-item-card::

.. toctree::
:maxdepth: 3

reference/space/index
35 changes: 35 additions & 0 deletions docs/api/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
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
17 changes: 17 additions & 0 deletions docs/api/reference/agents/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
AgentSetDF
==========

.. currentmodule:: mesa_frames

.. autoclass:: AgentSetPandas
:members:
:inherited-members:
:autosummary:
:autosummary-nosignatures:

.. autoclass:: AgentSetPolars
:members:
:inherited-members:
:autosummary:
:autosummary-nosignatures:

10 changes: 10 additions & 0 deletions docs/api/reference/model.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
ModelDF
=======

.. currentmodule:: mesa_frames

.. autoclass:: ModelDF
:members:
:inherited-members:
:autosummary:
:autosummary-nosignatures:
16 changes: 16 additions & 0 deletions docs/api/reference/space/grid/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
GridDF
======

.. currentmodule:: mesa_frames

.. autoclass:: GridPandas
:members:
:inherited-members:
:autosummary:
:autosummary-nosignatures:

.. autoclass:: GridPolars
:members:
:inherited-members:
:autosummary:
:autosummary-nosignatures:
8 changes: 8 additions & 0 deletions docs/api/reference/space/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Space
=====
This page provides a high-level overview of possible space objects for mesa-frames models.

.. toctree::
:maxdepth: 2

grid/index
File renamed without changes.
3 changes: 0 additions & 3 deletions docs/requirements.txt

This file was deleted.

29 changes: 1 addition & 28 deletions mesa_frames/abstract/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,21 +68,7 @@ def __init__(self, model):


class AgentContainer(CopyMixin):
"""An abstract class for containing agents. Defines the common interface for AgentSetDF and AgentsDF.

Properties
----------
model : ModelDF
Get the model associated with the AgentContainer.
random : Generator
Get the random number generator associated with the model.
agents : DataFrame | dict[str, DataFrame]
Get or set the agents in the AgentContainer.
active_agents : DataFrame | dict[str, DataFrame]
Get or set the active agents in the AgentContainer.
inactive_agents : DataFrame | dict[str, DataFrame]
Get the inactive agents in the AgentContainer.
"""
"""An abstract class for containing agents. Defines the common interface for AgentSetDF and AgentsDF."""

_copy_only_reference: list[str] = [
"_model",
Expand Down Expand Up @@ -741,19 +727,6 @@ def pos(self) -> DataFrame | dict[str, DataFrame]:
class AgentSetDF(AgentContainer, DataFrameMixin):
"""The AgentSetDF class is a container for agents of the same type.

Properties
----------
active_agents(self) -> DataFrame
Get the active agents in the AgentSetDF.
agents(self) -> DataFrame
Get or set the agents in the AgentSetDF.
inactive_agents(self) -> DataFrame
Get the inactive agents in the AgentSetDF.
model(self) -> ModelDF
Get the model associated with the AgentSetDF.
random(self) -> Generator
Get the random number generator associated with the model.

Parameters
----------
model : ModelDF
Expand Down
17 changes: 1 addition & 16 deletions mesa_frames/concrete/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,22 +67,7 @@ def step(self):


class AgentsDF(AgentContainer):
"""A collection of AgentSetDFs. All agents of the model are stored here.

Properties
----------
active_agents(self) -> dict[AgentSetDF, pd.DataFrame]
Get the active agents in the AgentsDF.
agents(self) -> dict[AgentSetDF, pd.DataFrame]
Get or set the agents in the AgentsDF.
inactive_agents(self) -> dict[AgentSetDF, pd.DataFrame]
Get the inactive agents in the AgentsDF.
model(self) -> ModelDF
Get the model associated with the AgentsDF.
random(self) -> np.random.Generator
Get the random number generator associated with the model.

"""
"""A collection of AgentSetDFs. All agents of the model are stored here."""

_agentsets: list[AgentSetDF]
_ids: pl.Series
Expand Down
6 changes: 0 additions & 6 deletions mesa_frames/concrete/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,6 @@ class ModelDF:
It includes the basic attributes and methods necessary for initializing and
running a simulation model.

Properties
----------
agents : AgentsDF
An AgentSet containing all agents in the model, generated from the _agents attribute.
agent_types : list of type
A list of different agent types present in the model.
"""

random: np.random.Generator
Expand Down
6 changes: 5 additions & 1 deletion mesa_frames/concrete/pandas/agentset.py
Original file line number Diff line number Diff line change
Expand Up @@ -62,12 +62,16 @@ def step(self):
from mesa_frames.concrete.pandas.mixin import PandasMixin
from mesa_frames.concrete.polars.agentset import AgentSetPolars
from mesa_frames.types_ import AgentPandasMask, PandasIdsLike
from mesa_frames.utils import copydoc

if TYPE_CHECKING:
from mesa_frames.concrete.model import ModelDF


class AgentSetPandas(AgentSetDF, PandasMixin): # noqa : D101
@copydoc(AgentSetDF)
class AgentSetPandas(AgentSetDF, PandasMixin):
"""pandas-based implementation of AgentSetDF."""

_agents: pd.DataFrame
_mask: pd.Series
_copy_with_method: dict[str, tuple[str, list[str]]] = {
Expand Down
2 changes: 2 additions & 0 deletions mesa_frames/concrete/pandas/mixin.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ def _some_private_method(self):


class PandasMixin(DataFrameMixin):
"""pandas-based implementation of DataFrame operations."""

def _df_add(
self,
df: pd.DataFrame,
Expand Down
Loading