Update tutorial

- add background information, - add model-specific information - add technical information - update code comments - update exercise 1 - delete .rst and .pngs due to addition of nbsphinx Co-authored-by: rht <rhtbot@protonmail.com> Co-authored-by: tpike3 <tpike3@gmu.edu>
projectmesa · May 15, 2023 · cbd7a43 · cbd7a43
1 parent 02592f3
commit cbd7a43
Show file tree

Hide file tree

Showing 19 changed files with 297 additions and 1,679 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -9,21 +9,13 @@ This folder contains the docs that build the docs for the core mesa code on read
 
 Updating docs can be confusing. Here are the basic setups.
 
-#### Create the rST files from ipynb files
-1. Change to the appropriate directory (usually docs/tutorials)
- * `cd tutorials`
-1. Create rST files using nbconvert
- * `jupyter nbconvert --to rST *.ipynb`
- * **Requires**
- * jupyter: `pip install jupyter`
- * [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`
 1. Update the docs. Save.
 1. Build the docs, from the inside of the docs folder.
  * **Requires** sphinx: `pip install sphinx`
+ * **Requires** nbsphinx: `pip install nbsphinx` (this will render the images from jupyter in the docs)
  * `make html`
 1. Commit the changes. If there are new files, you will have to explicit add them.
  * `git commit -am "Updating docs."`
@@ -33,7 +25,7 @@ Updating docs can be confusing. Here are the basic setups.
 
 ##### Update read the docs
 
-From this point, you will need to find someone that has access to readthedocs. Currently, that is [@jackiekazil](https://github.com/jackiekazil) and [@dmasad](https://github.com/dmasad).
+From this point, you will need to find someone that has access to readthedocs. Currently, that is [@jackiekazil](https://github.com/jackiekazil), [@rht](https://github.com/rht), and [@tpike3](https://github.com/dmasad).
 
 1. Accept the pull request into main.
 1. Log into readthedocs and launch a new build -- builds take about 10 minutes or so.

diff --git a/docs/index.rst b/docs/index.rst
@@ -95,7 +95,7 @@ ABM features users have shared that you may want to use in your model
  :maxdepth: 7
 
  Mesa Overview <overview>
- tutorials/intro_tutorial
+ tutorials/intro_tutorial.ipynb
  tutorials/adv_tutorial.ipynb
  Best Practices <best-practices>
  Useful Snippets <useful-snippets/snippets>

diff --git a/docs/tutorials/files/output_19_1.png b/docs/tutorials/files/output_19_1.png
diff --git a/docs/tutorials/intro_tutorial.ipynb b/docs/tutorials/intro_tutorial.ipynb