Fix Sphinx Website (#45)

* [gha] move into place * [docs] add API documentation page * [docs] summarize epiworldpy * [docs] turn of recursive generation * [doc] reintroduce epiworld summary * Bind Functions Again, Write Presentation (#46) * [gha] move into place * [docs] add API documentation page * [docs] summarize epiworldpy * [docs] turn of recursive generation * [doc] reintroduce epiworld summary * [bind] bind those functions again * [interactives] create, sequester * [cleanup] misc cleanup tasks * [presentation] polish * [dep] add `myst_parser`
UofUEpiBio · Nov 6, 2024 · f4cb110 · f4cb110
1 parent d3ac095
commit f4cb110
Show file tree

Hide file tree

Showing 10 changed files with 368 additions and 39 deletions.
diff --git a/.github/workflows/sphinx.yaml b/.github/workflows/sphinx.yaml
@@ -49,8 +49,8 @@ jobs:
       # Building
       - name: Render Quarto File
         run: |
-          quarto render README.qmd --to rst
-          mv README.rst docs/index.rst
+          quarto render README.qmd --to md
+          mv README.md docs/index.md
 
       - name: Build HTML using Sphinx
         run: sphinx-build -M html docs docs/build/

diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # epiworldpy: Python bindings for epiworld
 
 
-[![Pip
-Build](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml/badge.svg)](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml)
+[![](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml/badge.svg)](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml)
+[![](https://img.shields.io/pypi/v/epiworldpy.svg)](https://pypi.org/project/epiworldpy)
 
 This is a python wrapper of the [`epiworld c++`
 library](https://github.com/UofUEpiBio/epiworld/), an ABM simulation
@@ -16,8 +16,12 @@ target="_blank">implemented in R</a>.
 
 # Installation
 
-- clone this repository
-- `pip install ./epiworldpy`
+-   clone this repository
+-   `pip install ./epiworldpy`
+
+# API
+
+You can find API documentation on the <a href="/api.html">API page</a>.
 
 # Examples
 
@@ -31,7 +35,7 @@ use the following data:
 import epiworldpy as epiworld
 
 # Create a SEIR model (susceptible, exposed, infectious, recovered), representing COVID-19.
-covid19 = epiworld.ModelSEIR(
+covid19 = epiworld.ModelSEIRCONN(
   name              = 'covid-19',
   n                 = 10000,
   prevalence        = .01,
@@ -62,7 +66,7 @@ covid19.print(False)
      - Update infected individuals (runs daily)
 
     Virus(es):
-     - covid-19 (baseline prevalence: 1.00%)
+     - covid-19
 
     Tool(s):
      (none)
@@ -73,7 +77,7 @@ covid19.print(False)
      - Prob. Recovery       : 0.1400
      - Prob. Transmission   : 0.1000
 
-    <epiworldpy._core.ModelSEIRCONN at 0x1058e6e70>
+    <epiworldpy._core.ModelSEIRCONN at 0x10b9099f0>
 
 Let’s run it and to see what we get:
 
@@ -99,15 +103,15 @@ covid19.print(False)
     Number of entities  : 0
     Days (duration)     : 100 (of 100)
     Number of viruses   : 1
-    Last run elapsed t  : 14.00ms
-    Last run speed      : 70.84 million agents x day / second
+    Last run elapsed t  : 22.00ms
+    Last run speed      : 43.64 million agents x day / second
     Rewiring            : off
 
     Global events:
      - Update infected individuals (runs daily)
 
     Virus(es):
-     - covid-19 (baseline prevalence: 1.00%)
+     - covid-19
 
     Tool(s):
      (none)
@@ -130,7 +134,7 @@ covid19.print(False)
      - Infected     0.00  0.00  0.86  0.14
      - Recovered    0.00  0.00  0.00  1.00
 
-    <epiworldpy._core.ModelSEIRCONN at 0x1058e6e70>
+    <epiworldpy._core.ModelSEIRCONN at 0x10b9099f0>
 
 We can now visualize the model’s compartments:
 
@@ -173,8 +177,9 @@ plt.grid(True)
 plt.show()
 ```
 
-![COVID-19 SEIR model
-data](README_files/figure-commonmark/series-visualization-output-1.png)
+<img
+src="README_files/figure-markdown_strict/series-visualization-output-1.png"
+id="series-visualization" />
 
 We can get the effective reproductive number, over time, too:
 
@@ -186,7 +191,7 @@ plt.figure(figsize=(10, 6))
 
 for virus_id, virus_data in enumerate(reproductive_data):
     average_rts = list()
-    
+
     for date_data in virus_data:
         if not date_data:
             continue
@@ -204,8 +209,9 @@ plt.grid(True)
 plt.show()
 ```
 
-![COVID-19 SEIR model effective reproductive
-number](README_files/figure-commonmark/rt-visualization-output-1.png)
+<img
+src="README_files/figure-markdown_strict/rt-visualization-output-1.png"
+id="rt-visualization" />
 
 Let’s do the same for generation time:
 
@@ -246,8 +252,9 @@ plt.grid(True)
 plt.show()
 ```
 
-![COVID-19 SEIR model generation
-time](README_files/figure-commonmark/gentime-visualization-output-1.png)
+<img
+src="README_files/figure-markdown_strict/gentime-visualization-output-1.png"
+id="gentime-visualization" />
 
 Epiworld records agent-agent interactions, and we can graph those too.
 In the below example, we only track all cases stemming from a specific
@@ -271,10 +278,10 @@ fig, ax = plt.subplots(figsize=(6,4))
 to_track = { source[0] }
 def update(frame):
     ax.clear()
-    
+
     agents_involved_today = set()
     agents_relationships_we_care_about = []
-    
+
     # Get only the agents involved in the current frame.
     for i in range(len(start)):
         if start[i] <= frame <= end[i]:
@@ -312,5 +319,4 @@ plt.show()
 <!-- I couldn't figure out a way to get Quarto to do animations correctly so we're
   hardcoding a GIF. -->
 
-![Contact information from the COVID-19 SEIR model
-run](README_files/figure-commonmark/contact-visualization-output-1.gif)
+![](README_files/figure-markdown_strict/contact-visualization-output-1.gif)
diff --git a/README.qmd b/README.qmd
@@ -1,10 +1,10 @@
 ---
 format: gfm
-jupyter: python3
 title: "epiworldpy: Python bindings for epiworld"
 ---
 
-[![Pip Build](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml/badge.svg)](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml)
+[![](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml/badge.svg)](https://github.com/UofUEpiBio/epiworldpy/actions/workflows/pip.yaml)
+[![](https://img.shields.io/pypi/v/epiworldpy.svg)](https://pypi.org/project/epiworldpy)
 
 This is a python wrapper of the [`epiworld c++` library][epiworld-git], an ABM
 simulation engine. This is possible using the
@@ -20,9 +20,9 @@ The `epiworld` module is already
 
 # API
 
-You can find API documentation on the [API page](/api.html).
+You can find API documentation on the <a href="/api.html">API page</a>.
 
-# Examples 
+# Examples
 
 ## Basic
 
@@ -61,7 +61,7 @@ We can now visualize the model's compartments:
 
 ```{python}
 #| label: series-visualization
-#| fig-cap: "COVID-19 SEIR model data"
+#| fig-cap: ""
 
 import numpy as np
 import matplotlib.pyplot as plt
@@ -105,15 +105,15 @@ We can get the effective reproductive number, over time, too:
 
 ```{python}
 #| label: rt-visualization
-#| fig-cap: "COVID-19 SEIR model effective reproductive number"
+#| fig-cap: ""
 reproductive_data = covid19.get_db().get_reproductive_number()
 
 # Start the plotting!
 plt.figure(figsize=(10, 6))
 
 for virus_id, virus_data in enumerate(reproductive_data):
     average_rts = list()
-    
+
     for date_data in virus_data:
         if not date_data:
             continue
@@ -135,7 +135,7 @@ Let's do the same for generation time:
 
 ```{python}
 #| label: gentime-visualization
-#| fig-cap: "COVID-19 SEIR model generation time"
+#| fig-cap: ""
 from collections import defaultdict
 
 generation_time = covid19.get_db().get_generation_time()
@@ -176,7 +176,7 @@ Epiworld records agent-agent interactions, and we can graph those too. In the be
 
 ```{python}
 #| label: contact-visualization
-#| fig-cap: "COVID-19 SEIR model agent contact"
+#| fig-cap: ""
 #| eval: false
 
 import networkx as nx
@@ -196,10 +196,10 @@ fig, ax = plt.subplots(figsize=(6,4))
 to_track = { source[0] }
 def update(frame):
     ax.clear()
-    
+
     agents_involved_today = set()
     agents_relationships_we_care_about = []
-    
+
     # Get only the agents involved in the current frame.
     for i in range(len(start)):
         if start[i] <= frame <= end[i]:
@@ -236,7 +236,7 @@ plt.show()
 
 <!-- I couldn't figure out a way to get Quarto to do animations correctly so we're
   hardcoding a GIF. -->
-![Contact information from the COVID-19 SEIR model run](README_files/figure-commonmark/contact-visualization-output-1.gif)
+![](README_files/figure-markdown_strict/contact-visualization-output-1.gif)
 
 [epiworld-git]: https://github.com/UofUEpiBio/epiworld/
-[`pybind11`]: https://pybind11.readthedocs.io/en/stable/
+[`pybind11`]: https://pybind11.readthedocs.io/en/stable/
diff --git a/...onmark/contact-visualization-output-1.gif → ...strict/contact-visualization-output-1.gif b/...onmark/contact-visualization-output-1.gif → ...strict/contact-visualization-output-1.gif
diff --git a/...onmark/gentime-visualization-output-1.png → ...strict/gentime-visualization-output-1.png b/...onmark/gentime-visualization-output-1.png → ...strict/gentime-visualization-output-1.png
diff --git a/...-commonmark/rt-visualization-output-1.png → ...down_strict/rt-visualization-output-1.png b/...-commonmark/rt-visualization-output-1.png → ...down_strict/rt-visualization-output-1.png
diff --git a/...monmark/series-visualization-output-1.png → ..._strict/series-visualization-output-1.png b/...monmark/series-visualization-output-1.png → ..._strict/series-visualization-output-1.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,6 +31,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
+    'myst_parser',
 ]
 
 autosummary_generate = True
@@ -41,7 +42,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'