Revamp documentation content and navigation (#190)

* Revamp documentation content and navigation

* Merge branch 'main' of https://github.com/projectmesa/mesa-frames into split/docs-and-toptexts

* update uv.lock

* Fix trigger condition in MoneyModel to use steps instead of schedule.steps

* Enable notebook execution in mkdocs configuration

* Refactor CLI model and agent options to use single string type

* Remove outdated documentation files for DataCollector tutorial and benchmarks

* Add theme-aware image swapping and benchmark plots to documentation

* Refactor Sugarscape model and agent interactions for improved performance

- Updated Sugarscape model to use direct property access for empty and full cells, reducing unnecessary joins.
- Enhanced AntDFBase agent's eat method to optimize sugar harvesting by joining agent positions with cell properties directly.
- Introduced cell_properties property in AbstractDiscreteSpace to provide direct access to cell attributes without agent occupancy.
- Implemented get_cell_properties method for efficient retrieval of cell properties at specified coordinates.
- Improved AbstractAgentSet's handling of agent indices to ensure proper DataFrame structure and maintain order.
- Enhanced Grid class to support efficient neighborhood retrieval and cell property management, including dense row-major optimizations.
- Added tests for get/set cell property functionality in both dense and toroidal grid configurations to ensure correctness and robustness.

* update plots

* delete old plot

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix commented installation command in Data Collector tutorial

* Update benchmark plot paths in README for improved organization

* revert changes to main

* Update formatting in README and ROADMAP for consistency

* Refactor README layout for improved readability and organization

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: adamamer20

.gitignore

@@ -155,10 +155,11 @@ cython_debug/
 llm_rules.md
 .python-version
 
-benchmarks/**/results
-benchmarks/**/plots
-docs/api/_build/*
-docs/api/reference/*
-examples/**/results
-docs/general/**/data_*
-docs/site/*
+benchmarks/results/*
+docs/api/_build
+docs/api/reference/**/mesa_frames.*.rst
+examples/**/results/*
+docs/general/tutorials/data_csv
+docs/general/tutorials/data_parquet
+docs/general/tutorials/*.ipynb
+docs/site

CHANGELOG.md

@@ -0,0 +1,40 @@
+## Version 0.1.0-alpha — 2024-08-28
+
+## What's Changed
+
+* Refactoring mesa.Agent, mesa.AgentSet, mesa.Model -> AgentSetDF, AgentsDF, ModelDF by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/8>
+* setup: Migrate from setup.py to pyproject.toml by @rht in <https://github.com/adamamer20/mesa-frames/pull/13>
+* ci: Add pre-commit configuration by @rht in <https://github.com/adamamer20/mesa-frames/pull/14>
+* Merge requirements.txt into pyproject.toml by @rht in <https://github.com/adamamer20/mesa-frames/pull/15>
+* ci: Add GA for tests by @rht in <https://github.com/adamamer20/mesa-frames/pull/17>
+* Changes to AgentSetDF and AgentsDF before time.py -> CopyMixin by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/16>
+* benchmark: Split Polars agent into native and concise by @rht in <https://github.com/adamamer20/mesa-frames/pull/23>
+* benchmark: Split pandas agent into native and concise by @rht in <https://github.com/adamamer20/mesa-frames/pull/24>
+* speed up mesa readme_plot script by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/26>
+* Adding DataFrameMixin for improved reusability/encapsulation by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/27>
+* Abstract SpaceDF by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/29>
+* Adding Abstract DiscreteSpaceDF by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/30>
+* Adding abstract GridDF by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/32>
+* Additional methods and fixes to DataFrameMixin by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/43>
+* Concrete GridPandas by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/44>
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in <https://github.com/adamamer20/mesa-frames/pull/55>
+* Fixes and Tests for PolarsMixin by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/56>
+* Adding Comparison and Indexing methods to DataFrameMixin by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/58>
+* Concrete GridPolars by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/60>
+* Sugarscape Instantaneous Growback (Pandas-with-loop implementation) by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/63>
+* Adding pydoclint and properly format docstring by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/69>
+* Docs with material-from-mkdocs by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/70>
+* Enforce correct numpy docstring formatting with ruff.pydocstyle by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/74>
+* API Documentation with Sphinx by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/75>
+* Move images from docs to docs/general to make it available for mkdocs by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/79>
+* Adding user guide by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/81>
+* Adding SugarScape IG (polars with loops) by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/71>
+* Automatic publishing on PyPI on new release by @adamamer20 in <https://github.com/adamamer20/mesa-frames/pull/77>
+
+## New Contributors
+
+* @adamamer20 made their first contribution in <https://github.com/adamamer20/mesa-frames/pull/8>
+* @rht made their first contribution in <https://github.com/adamamer20/mesa-frames/pull/13>
+* @pre-commit-ci made their first contribution in <https://github.com/adamamer20/mesa-frames/pull/55>
+
+**Full Changelog**: <https://github.com/adamamer20/mesa-frames/commits/v0.1.0-alpha>

CONTRIBUTING.md

@@ -15,16 +15,22 @@ Before contributing, we recommend reviewing our [roadmap](https://mesa.github.io
 Before you begin contributing, ensure that you have the necessary tools installed:
 
 - **Install Python** (at least the version specified in `requires-python` of `pyproject.toml`). 🐍
-- We recommend using a virtual environment manager like:
-  - [Astral's UV](https://docs.astral.sh/uv/#installation) 🌟
-  - [Hatch](https://hatch.pypa.io/latest/install/) 🏗️
+
+-- We recommend using a virtual environment manager like:
+
+    - [Astral's UV](https://docs.astral.sh/uv/#installation) 🌟
+    - [Hatch](https://hatch.pypa.io/latest/install/) 🏗️
+
 - Install **pre-commit** to enforce code quality standards before pushing changes:
+
   - [Pre-commit installation guide](https://pre-commit.com/#install) ✅
   - [More about pre-commit hooks](https://stackoverflow.com/collectives/articles/71270196/how-to-use-pre-commit-to-automatically-correct-commits-and-merge-requests-with-g)
-- If using **VS Code**, consider installing these extensions to automatically enforce formatting:
-  - [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) – Python linting & formatting 🐾
-  - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) – Markdown linting (for documentation) ✍️
-  - [Git Hooks](https://marketplace.visualstudio.com/items?itemName=lakshmikanthayyadevara.githooks) – Automatically runs & visualizes pre-commit hooks 🔗
+
+-- If using **VS Code**, consider installing these extensions to automatically enforce formatting:
+
+    - [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) – Python linting & formatting 🐾
+    - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) – Markdown linting (for documentation) ✍️
+    - [Git Hooks](https://marketplace.visualstudio.com/items?itemName=lakshmikanthayyadevara.githooks) – Automatically runs & visualizes pre-commit hooks 🔗
 
 ---
 
@@ -58,28 +64,13 @@ Before you begin contributing, ensure that you have the necessary tools installe
 
 #### **Step 3: Install Dependencies** 📦
 
-It is recommended to set up a virtual environment before installing dependencies.
-
-- **Using UV**:
-
-  ```sh
-  uv add --dev .[dev]
-  ```
-
-- **Using Hatch**:
+We manage the development environment with [uv](https://docs.astral.sh/uv/):
 
-  ```sh
-  hatch env create dev
-  ```
+```sh
+uv sync --all-extras
+```
 
-- **Using Standard Python**:
-
-  ```sh
-  python3 -m venv myenv
-  source myenv/bin/activate  # macOS/Linux
-  myenv\Scripts\activate    # Windows
-  pip install -e ".[dev]"
-  ```
+This creates `.venv/` and installs mesa-frames with the development extras.
 
 #### **Step 4: Make and Commit Changes** ✨
 
@@ -99,33 +90,35 @@ It is recommended to set up a virtual environment before installing dependencies
 - **Run pre-commit hooks** to enforce code quality standards:
 
   ```sh
-  pre-commit run
+  uv run pre-commit run -a
   ```
 
 - **Run tests** to ensure your contribution does not break functionality:
 
   ```sh
-  pytest --cov
+  uv run pytest -q --cov=mesa_frames --cov-report=term-missing
   ```
 
-  - If using UV: `uv run pytest --cov`
+-- **Optional: Runtime Type Checking (beartype)** 🔍
 
-- **Optional: Enable runtime type checking** during development for enhanced type safety:
+  You can enable stricter runtime validation of function arguments/returns with `beartype` during local development:
 
   ```sh
-  MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest --cov
+  MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest -q --cov=mesa_frames --cov-report=term-missing
   ```
 
-  !!! tip "Automatically Enabled"
-      Runtime type checking is automatically enabled in these scenarios:
+  Quick facts:
 
-      - **Hatch development environment** (`hatch shell dev`)
-      - **VS Code debugging** (when using the debugger)
-      - **VS Code testing** (when running tests through VS Code's testing interface)
+- Automatically enabled in: Hatch dev env (`hatch shell dev`), VS Code debugger, and VS Code test runs.
+- Enable manually by exporting `MESA_FRAMES_RUNTIME_TYPECHECKING=1` (any of 1/true/yes).
+- Use only for development/debugging; adds overhead—disable for performance measurements or large simulations.
+- Unset with your shell (e.g. `unset`/`Remove-Item Env:` depending on shell) to turn it off.
 
-      No manual setup needed in these environments!
+  Example for a one-off test run:
 
-  For more details on runtime type checking, see the [Development Guidelines](https://mesa.github.io/mesa-frames/development/).
+  ```sh
+  MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest -q
+  ```
 
 #### **Step 6: Documentation Updates (If Needed)** 📖
 
@@ -135,8 +128,7 @@ It is recommended to set up a virtual environment before installing dependencies
   - Preview your changes by running:
 
     ```sh
-    mkdocs serve
-    uv run mkdocs serve #If using uv
+    uv run mkdocs serve
     ```
 
   - Open `http://127.0.0.1:8000` in your browser to verify documentation updates.