Skip to content

Commit

Permalink
create readthedocs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wang-boyu
wang-boyu committed Sep 4, 2022
1 parent 8d779e9 commit 2009d9a
Show file tree
Hide file tree
Showing 22 changed files with 1,543 additions and 278 deletions.
22 changes: 22 additions & 0 deletions .readthedocs.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py

# Optionally build your docs in additional formats such as PDF
formats:
- pdf

# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.8
install:
- method: pip
path: .
extra_requirements:
- docs
101 changes: 8 additions & 93 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Mesa-Geo: a GIS extension for the Mesa agent-based modeling framework in Python
# Mesa-Geo: GIS Extension for Mesa Agent-Based Modeling

Mesa-Geo implements a `GeoSpace` that can host GIS-based `GeoAgents`, which are like normal Agents, except they have a `geometry` attribute that is a [Shapely object](https://shapely.readthedocs.io/en/latest/manual.html) and a `crs` attribute for its Coordinate Reference System. You can use `Shapely` directly to create arbitrary geometries, but in most cases you will want to import your geometries from a file. Mesa-Geo allows you to create GeoAgents from any vector data file (e.g. shapefiles), valid GeoJSON objects or a GeoPandas GeoDataFrame.

## Installation
## Using Mesa-Geo

To install Mesa-Geo on linux or macOS run

Expand All @@ -23,99 +23,14 @@ Since Mesa-Geo is in early development you could also install the latest version
pip install -e git+https://github.com/projectmesa/mesa-geo.git#egg=mesa-geo
```

## Getting started
Take a look at the [examples](https://github.com/projectmesa/mesa-geo/tree/main/examples) folder for sample models demonstrating Mesa-Geo features.

You should be familiar with how [Mesa](https://github.com/projectmesa/mesa) works.
For more help on using Mesa-Geo, check out the following resources:

So let's get started with some geometries! We will work with [records of US states](http://eric.clst.org/Stuff/USGeoJSON). We use the `requests` library to retrieve the data, but of course you can work with local data.

```python
from mesa_geo import GeoSpace, GeoAgent, AgentCreator
from mesa import Model
import requests
url = 'http://eric.clst.org/assets/wiki/uploads/Stuff/gz_2010_us_040_00_20m.json'
r = requests.get(url)
geojson_states = r.json()
```

First we create a `State` Agent and a `GeoModel`. Both should look familiar if you have worked with mesa before.

```python
class State(GeoAgent):
def __init__(self, unique_id, model, geometry, crs):
super().__init__(unique_id, model, geometry, crs)

class GeoModel(Model):
def __init__(self):
self.space = GeoSpace()

ac = AgentCreator(agent_class=State, model=self)
agents = ac.from_GeoJSON(GeoJSON=geojson_states, unique_id="NAME")
self.space.add_agents(agents)
```

In the `GeoModel` we first create an instance of AgentCreator, where we provide the Agent class (State) and its required arguments, except geometry and unique_id. We then use the `.from_GeoJSON` function to create our agents from the geometries in the GeoJSON file. We provide the feature "name" as the key from which the agents get their unique_ids.
Finally, we add the agents to the GeoSpace

Let's instantiate our model and look at one of the agents:

```python
m = GeoModel()

agent = m.space.agents[0]
print(agent.unique_id)
agent.geometry
```

If you work in the Jupyter Notebook your output should give you the name of the state and a visual representation of the geometry.

Arizona

!['Arizona state borders'](output_3_1.svg)

By default the AgentCreator also sets further agent attributes from the Feature properties.

```python
agent.CENSUSAREA
```

113594.084

Let's start to do some spatial analysis. We can use usual Mesa function names to get neighboring states

```python
neighbors = m.space.get_neighbors(agent)
print([a.unique_id for a in neighbors])
```

California
Colorado
New Mexico
Utah
Nevada

To get a list of all states within a certain distance you can use the following

```python
[a.unique_id for a in m.space.get_neighbors_within_distance(agent, 600000)]
```

['California',
'Colorado',
'New Mexico',
'Oklahoma',
'Wyoming',
'Idaho',
'Utah',
'Nevada']

The unit for the distance depends on the coordinate reference system (CRS) of the GeoSpace. Since we did not specify the CRS, Mesa-Geo defaults to the 'Web Mercator' projection (in meters). If you want to do some serious measurements you should always set an appropriate CRS, since the accuracy of Web Mercator declines with distance from the equator. We can achieve this by initializing the AgentCreator and the GeoSpace with the `crs` keyword `crs="epsg:2163"`. Mesa-Geo then transforms all coordinates from the GeoJSON geographic coordinates into the set crs.

## Going further

To get a deeper understanding of Mesa-Geo you should check out the GeoSchelling example. It implements a Leaflet visualization which is similar to use as the CanvasGridVisualization of Mesa.

To add further functionality, I need feedback on which functionality is desired by users. Please post a message at [Mesa-Geo discussions](https://github.com/projectmesa/mesa-geo/discussions) or open an [issue](https://github.com/projectmesa/mesa-geo/issues) if you have any ideas or recommendations.
- [Introductory Tutorial](http://mesa-geo.readthedocs.org/en/main/tutorials/intro_tutorial.html)
- [Docs](http://mesa-geo.readthedocs.org/en/main/)
- [Mesa-Geo Discussions](https://github.com/projectmesa/mesa-geo/discussions)
- [PyPI](https://pypi.org/project/mesa-geo/)

## Contributing to Mesa-Geo

Expand Down
177 changes: 177 additions & 0 deletions docs/Makefile
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build

# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"

clean:
rm -rf $(BUILDDIR)/*

html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."

json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."

htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Mesa-Geo.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Mesa-Geo.qhc"

devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Mesa-Geo"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Mesa-Geo"
@echo "# devhelp"

epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."

latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."

info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."

doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."

pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
52 changes: 52 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
Docs for Mesa-Geo
=============

The readable version of the docs is hosted at [mesa-geo.readthedocs.org](http://mesa-geo.readthedocs.org/).

This folder contains the docs that build the docs for Mesa-Geo on readthdocs.

## How to publish updates to the docs

Updating docs can be confusing. Here are the basic setups.

### Install dependencies

From the project root, install the dependencies for building the docs:

```shell
pip install -e ".[docs]"
```

### Create the markdown files from ipynb files

1. Change to the appropriate directory (usually docs/tutorials)
* `cd tutorials`
2. Create markdown files using nbconvert
* `jupyter nbconvert --to markdown *.ipynb`
* **Requires** [pandoc](http://pandoc.org/installing.html)

### Submit a pull request with updates

1. Create branch (either via branching or fork of repo) -- try to use a descriptive name.
* `git checkout -b doc-updates`
2. Update the docs. Save.
3. Build the docs, from the inside of the docs folder.
* `make html`
4. Commit the changes. If there are new files, you will have to explicit add them.
* `git commit -am "update docs"`
5. Push the branch.
* `git push origin doc-updates`
6. From here you will want to submit a pull request to main.

### Update read the docs

From this point, you will need to find someone that has access to readthedocs. Currently, that is [@wang-boyu](https://github.com/wang-boyu).

1. Accept the pull request into main.
2. Log into readthedocs and launch a new build -- builds take about 10 minutes or so.

## Helpful Sphnix tips
* Build html from docs:
* `make html`
* Autogenerate / update sphninx from docstrings (replace your name as the author):
* `sphinx-apidoc -A "Jackie Kazil" -F -o docs mesa_geo/`
12 changes: 12 additions & 0 deletions docs/apis/api_main.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# APIs

```{toctree}
---
maxdepth: 3
---
GeoBase <geo_base>
GeoAgent <geoagent>
GeoSpace <geospace>
Raster Layers <raster_layers>
visualization
```
4 changes: 4 additions & 0 deletions docs/apis/geo_base.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. automodule:: mesa_geo.geo_base
:members:
:inherited-members:
:undoc-members:
4 changes: 4 additions & 0 deletions docs/apis/geoagent.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. automodule:: mesa_geo.geoagent
:members:
:inherited-members:
:undoc-members:
Loading

0 comments on commit 2009d9a

Please sign in to comment.