Docs with material-from-mkdocs (#70)

* removing old docs * removing docs from codespell * adding mkdocs-material * adding docstring generator and jupyter extension * creating new project with mkdocs * moving to docs and appending mesa-frames path * adding markdownlint to pre-commit hooks * moving mkdocs to root folder * modeling mkdocs on polars * adding automatic fixing for markdown lint * update markdownlint * adding index.md * renaming to .markdownlint.json * creating api docs * adding pydoclint * pydoclint fix for abstract/agents.py * adding DataFrameInput type hint * pydoclint fix for mesa_frames/abstract/mixin * adding raises skip checking * allowing init docstring (clearer) * pydoclint fix for mesa_frames/abstract/space * pydoclint fixes for mesa_frames.concrete.agents * pydoclint fixes for mesa_frames/concrete/model * pydoclint fixes for mesa_frames/concrete/polars/agentset * explaining pre-commit use * removing mkdocstrings (better to do it with sphinx) * removing api documentation with mkdocs * moving mkdocs.yml to docs folder * automatic gh action for publishing mkdocs * moving mkdocs.yml to root * mkdocs.yml in root directory * removing material-for-mkdocs branch * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * change Pandas to pandas --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
projectmesa · Aug 21, 2024 · 18fe881 · 18fe881
1 parent 7075624
commit 18fe881
Show file tree

Hide file tree

Showing 14 changed files with 243 additions and 2,432 deletions.
diff --git a/.github/workflows/docs-gh-pages.yml b/.github/workflows/docs-gh-pages.yml
@@ -0,0 +1,19 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: docs/requirements.txt
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -0,0 +1,3 @@
+{
+    "MD013": false
+}
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -31,10 +31,17 @@ repos:
       args: [
         "--ignore-words",
         ".codespellignore",
-        "--exclude-file",
-        "docs/api/search.js",
       ]
-- repo: https://github.com/jsh9/pydoclint
+- repo: https://github.com/DavidAnson/markdownlint-cli2 #For formatting markdown for documentation
+  rev: v0.13.0
+  hooks:
+    - id: markdownlint-cli2
+      args: [
+        "--fix",
+        "--config",
+        ".markdownlint.json",
+      ]
+- repo: https://github.com/jsh9/pydoclint #For checking docstrings
   rev: 0.5.6
   hooks:
     - id: pydoclint

diff --git a/README.md b/README.md
@@ -4,10 +4,10 @@ mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) f
 
 ## Why DataFrames?
 
-DataFrames are optimized for simultaneous operations through [SIMD processing](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data). At the moment, mesa-frames supports the use of two main libraries: Pandas and Polars.
+DataFrames are optimized for simultaneous operations through [SIMD processing](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data). At the moment, mesa-frames supports the use of two main libraries: pandas and Polars.
 
-- [Pandas](https://pandas.pydata.org/) is a popular data-manipulation Python library, developed using C and Cython. Pandas is known for its ease of use, allowing for declarative programming and high performance.
-- [Polars](https://pola.rs/) is a new DataFrame library with a syntax similar to Pandas but with several innovations, including a backend implemented in Rust, the Apache Arrow memory format, query optimization, and support for larger-than-memory DataFrames.
+- [pandas](https://pandas.pydata.org/) is a popular data-manipulation Python library, developed using C and Cython. pandas is known for its ease of use, allowing for declarative programming and high performance.
+- [Polars](https://pola.rs/) is a new DataFrame library with a syntax similar to pandas but with several innovations, including a backend implemented in Rust, the Apache Arrow memory format, query optimization, and support for larger-than-memory DataFrames.
 
 The following is a performance graph showing execution time using mesa and mesa-frames for the [Boltzmann Wealth model](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html).
 
@@ -43,6 +43,7 @@ conda activate myenv
 ```
 
 Then, to install mesa-frames itself:
+
 ```bash
 # For pandas backend
 pip install -e .[pandas]
@@ -66,14 +67,14 @@ source myenv/bin/activate  # On Windows, use `myenv\Scripts\activate`
 ```
 
 Then, to install mesa-frames itself:
+
 ```bash
 # For pandas backend
 pip install -e .[pandas]
 # Alternatively, for Polars backend
 pip install -e .[polars]
 ```
 
-
 ## Usage
 
 **Note:** mesa-frames is currently in its early stages of development. As such, the usage patterns and API are subject to change. Breaking changes may be introduced. Reports of feedback and issues are encouraged.

diff --git a/docs/api/index.html b/docs/api/index.html
diff --git a/docs/api/mesa_frames.html b/docs/api/mesa_frames.html
diff --git a/docs/api/mesa_frames/agent.html b/docs/api/mesa_frames/agent.html
diff --git a/docs/api/mesa_frames/model.html b/docs/api/mesa_frames/model.html
diff --git a/docs/api/search.js b/docs/api/search.js
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,79 @@
+# Welcome to mesa-frames 🚀
+
+mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax.
+
+## Why DataFrames? 📊
+
+DataFrames are optimized for simultaneous operations through [SIMD processing](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data). Currently, mesa-frames supports two main libraries:
+
+- [pandas](https://pandas.pydata.org/): A popular data-manipulation Python library, known for its ease of use and high performance.
+- [Polars](https://pola.rs/): A new DataFrame library with a Rust backend, offering innovations like Apache Arrow memory format and support for larger-than-memory DataFrames.
+
+## Performance Boost 🏎️
+
+Check out our performance graphs comparing mesa and mesa-frames for the [Boltzmann Wealth model](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html):
+
+![Performance Graph](images/readme_plot_0.png)
+
+![Performance Graph without Mesa](images/readme_plot_1.png)
+
+## Quick Start 🚀
+
+### Installation
+
+```bash
+git clone https://github.com/adamamer20/mesa_frames.git
+cd mesa_frames
+pip install -e .[pandas]  # For pandas backend
+# or
+pip install -e .[polars]  # For Polars backend
+```
+
+### Basic Usage
+
+Here's a quick example of how to create an agent set using mesa-frames:
+
+```python
+from mesa-frames import AgentSetPolars, ModelDF
+
+class MoneyAgentPolars(AgentSetPolars):
+    def __init__(self, n: int, model: ModelDF):
+        super().__init__(model)
+        self += pl.DataFrame(
+            {"unique_id": pl.arange(n, eager=True), "wealth": pl.ones(n, eager=True)}
+        )
+
+    def step(self) -> None:
+        self.do("give_money")
+
+    def give_money(self):
+        # ... (implementation details)
+
+class MoneyModelDF(ModelDF):
+    def __init__(self, N: int):
+        super().__init__()
+        self.agents += MoneyAgentPolars(N, self)
+
+    def step(self):
+        self.agents.do("step")
+
+    def run_model(self, n):
+        for _ in range(n):
+            self.step()
+```
+
+## What's Next? 🔮
+
+- API refinement for seamless transition from mesa
+- Support for default mesa functions
+- GPU functionality (cuDF and Rapids)
+- Automatic vectorization of existing mesa models
+- Backend-independent AgentSet class
+
+## Get Involved! 🤝
+
+mesa-frames is in its early stages, and we welcome your feedback and contributions! Check out our [GitHub repository](https://github.com/adamamer20/mesa_frames) to get started.
+
+## License
+
+mesa-frames is available under the MIT License. See the [LICENSE](https://github.com/adamamer20/mesa_frames/blob/main/LICENSE) file for full details.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs-jupyter
+mkdocs-git-revision-date-localized-plugin
+mkdocs-minify-plugin
diff --git a/mesa_frames/types_.py b/mesa_frames/types_.py
@@ -15,7 +15,7 @@
 AgnosticAgentMask = Sequence[int] | int | Literal["all", "active"] | None
 AgnosticIds = int | Collection[int]
 
-###----- Pandas Types -----###
+###----- pandas Types -----###
 
 PandasMask = pd.Series | pd.DataFrame | AgnosticMask
 AgentPandasMask = AgnosticAgentMask | pd.Series | pd.DataFrame

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,114 @@
+# Project information
+site_name: mesa-frames
+site_url: https://adamamer20.github.io/mesa-frames
+repo_url: https://github.com/adamamer20/mesa-frames
+repo_name: adamamer20/mesa-frames
+
+# Theme configuration
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - navigation.indexes
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon:
+    repo: fontawesome/brands/github
+
+# Plugins
+plugins:
+  - search
+  - mkdocs-jupyter
+  - git-revision-date-localized:
+      enable_creation_date: true
+  - minify:
+      minify_html: true
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: adamamer20
+      repo: mesa-frames
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra JavaScript and CSS for rendering
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+# Customization
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/adamamer20
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/mesa-frames/
+
+# Navigation
+nav:
+  - Home: index.md
+  - User Guide:
+    - Getting Started: user-guide/getting-started.md
+    - Tutorial: user-guide/tutorial.md
+  - API Reference: api/index.html
+  - Development:
+    - Contributing: development/contributing.md
+    - Changelog: development/changelog.md
+  - About:
+    - License: about/license.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -26,10 +26,17 @@ polars = [
   #"geopolars" (currently in pre-alpha)
 ]
 
-dev = [
-  "mesa_frames[pandas,polars]",
+docs = [
   "perfplot", #readme_script
   "seaborn", #readme_script
+  "mkdocs-material",
+  "mkdocs-jupyter",
+  "mkdocs-git-revision-date-localized-plugin",
+  "mkdocs-minify-plugin"
+]
+
+dev = [
+  "mesa_frames[pandas, polars, docs]",
   "pytest",
   "pytest-cov",
   "typeguard",