patch for readthedocs (#83)

* updates for readthedocs
* fix zenodo query

.github/workflows/pypi-release.yml

@@ -25,7 +25,7 @@ jobs:
         login: "${{ secrets.REPO_USER }}"
         token: "${{ secrets.REPO_PAT }}"
         # part defaults to patch
-        part: minor
+        # part: minor
     - name: Create dist
       run: |
         pip install pybind11 numpy build

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt

docs/developer.md

@@ -17,7 +17,7 @@ The instructions below assume you've already forked and cloned a local copy of t
 
 ## Development environment
 
-See [system requirements](../..#system-requirements) and use:
+See [system requirements](index.md#system-requirements) and use:
 
 ```bash
 pip install -e .[dev] # add ,parallel,geospatial as necessary

docs/examples/option.md

@@ -5,7 +5,7 @@ This example showcases how to run parallel simulations, each with identical rand
 {{ include_snippet("./docs/examples/src.md", show_filename=False) }}
 
 !!! note "Optional dependencies"
-    This example requires optional dependencies, see [system requirements](../..#system-requirements) and use:
+    This example requires optional dependencies, see [system requirements](../index.md#system-requirements) and use:
 
     `pip install neworder[parallel]`
 

docs/examples/parallel.md

@@ -13,7 +13,7 @@ Finally, one process acquires the entire population and prints a summary of the
 {{ include_snippet("./docs/examples/src.md", show_filename=False) }}
 
 !!! note "Optional dependencies"
-    This example requires optional dependencies, see [system requirements](../..#system-requirements) and use:
+    This example requires optional dependencies, see [system requirements](../index.md#system-requirements) and use:
 
     `pip install neworder[parallel]`
 
@@ -24,7 +24,7 @@ Firstly, we import the necessary modules and check we are running in parallel mo
 {{ include_snippet("examples/parallel/model.py", "setup") }}
 
 !!! note "MPI"
-    *neworder* uses the `mpi4py` package to provide MPI functionality, which in turn requires an MPI installation on the host (see [system requirements](../..#system-requirements)). The attributes `neworder.mpi.COMM` (the MPI communicator), `neworder.mpi.RANK` and `neworder.mpi.SIZE` are provided for convenience.
+    *neworder* uses the `mpi4py` package to provide MPI functionality, which in turn requires an MPI installation on the host (see [system requirements](../index.md#system-requirements)). The attributes `neworder.mpi.COMM` (the MPI communicator), `neworder.mpi.RANK` and `neworder.mpi.SIZE` are provided for convenience.
 
 As always, the neworder framework expects an instance of a model class, subclassed from `neworder.Model`, which in turn requires a timeline, in this case a `neworder.LinearTimeline` object:
 

docs/examples/src.md

@@ -1,5 +1,5 @@
 !!! note "Examples Source Code"
     The code for all the examples can be obtained by either:
 
-    - pulling the docker image `virgesmith/neworder:latest` (more [here](/#docker)), or
+    - pulling the docker image `virgesmith/neworder:latest` (more [here](../index.md/#docker)), or
     - installing neworder, downloading the source code archive from the `neworder` [releases](https://github.com/virgesmith/neworder/releases) page and extracting the `examples` subdirectory.

docs/macros.py

@@ -1,6 +1,8 @@
 # macros for mkdocs-macros-plugin
 import os
 import requests
+import importlib
+from datetime import datetime
 
 _inline_code_styles = {
   ".py": "python",
@@ -13,16 +15,39 @@
   ".md": None
 }
 
+# this is the overall record id, not a specific version
+_NEWORDER_ZENODO_ID = 4031821
+
+
+def write_requirements() -> None:
+  try:
+    with open("docs/requirements.txt", "w") as fd:
+      fd.write(f"""# DO NOT EDIT
+# auto-generated @ {datetime.now()} by docs/macros.py::write_requirements()
+# required by readthedocs.io
+""")
+      fd.writelines(f"{dep}=={importlib.metadata.version(dep)}\n" for dep in [
+        "mkdocs",
+        "mkdocs-macros-plugin",
+        "mkdocs-material",
+        "mkdocs-material-extensions",
+        "mkdocs-video",
+        "requests"
+      ])
+  # ignore any error, this should only run in a dev env anyway
+  except:
+    pass
+
 
 def define_env(env):
 
   @env.macro
   def insert_zenodo_field(*keys: str):
     """ This is the *released* version not the dev one """
     try:
-      response = requests.get('https://zenodo.org/api/deposit/depositions/7838395', params={'access_token': os.getenv("ZENODO_PAT")})
+      response = requests.get('https://zenodo.org/api/records', params={'q': _NEWORDER_ZENODO_ID, 'access_token': os.getenv("ZENODO_PAT")})
       response.raise_for_status()
-      result = response.json()
+      result = response.json()["hits"]["hits"][0]
       for k in keys:
         result = result[k]
       return result
@@ -62,3 +87,4 @@ def include_snippet(filename, tag=None, show_filename=True):
     else:
       return "".join(lines) + footer
 
+write_requirements()

docs/overview.md

@@ -52,7 +52,6 @@ symbol     | type              | description
 `at_end`   | `bool` property   | whether the timeline has reached it's end point
 `dt`       | `float` property  | the size of the current timestep
 `end`      | `Any` property    | the end time of the timeline
-`index`    | `int` property    | the index of the current timestep
 `_next`    | `None` method     | move to the next timestep (for internal use by model, should not normally be called in client code)
 `nsteps`   | `int` property    | the total number of timesteps
 `start`    | `Any` property    | the start time of the timeline
@@ -81,7 +80,7 @@ See the [Conway](examples/conway.md) example for implementations.
 
 #### Graph
 
-The `GeospatialGraph` class provides a wrapper around the `networkx` and `osmnx` packages, and provides methods for computing shortes paths, isochrones, and subgraphs as well as identifying edges connected to nodes and vice versa. Due to its heavy dependencies, it is not part of the core `neworder` package - the implementation is in the [infection](examples/infection.md) example.
+The `GeospatialGraph` class provides a wrapper around the `networkx` and `osmnx` packages, and provides methods for computing shortest paths, isochrones, and subgraphs as well as identifying edges connected to nodes and vice versa. Due to its heavy dependencies, it an extra - installed using `pip install neworder[geospatial]`.
 
 ### Model
 
@@ -119,4 +118,4 @@ New users should take a look at the examples, which cover a range of application
 
 You should also bear in mind that while python is a *dynamically typed* language, C++ is *statically typed*. If an argument to a *neworder* method is not the correct type, it will fail immediately (as opposed to python, which will fail only if an invalid operation for the given type is attempted). Note also that `neworder`'s python code has type annotations.
 
-* the `neworder.df.transition` function is *over 2 or 3 orders of magnitude faster* than an equivalent python implementation depending on the length of the dataset, and still an order of magnitude faster that an optimised python implementation.
+* the `neworder.df.transition` function is *over 2 or 3 orders of magnitude faster* than a (naive) equivalent python implementation depending on the length of the dataset, and still an order of magnitude faster than an optimised python implementation.

docs/requirements.txt

@@ -0,0 +1,9 @@
+# DO NOT EDIT
+# auto-generated @ 2023-08-30 07:58:47.663213 by docs/macros.py::write_requirements()
+# required by readthedocs.io
+mkdocs==1.5.2
+mkdocs-macros-plugin==1.0.4
+mkdocs-material==9.2.5
+mkdocs-material-extensions==1.1.1
+mkdocs-video==1.5.0
+requests==2.31.0

mkdocs.yml

@@ -67,5 +67,4 @@ nav:
     - Developer: developer.md
     - Support: support.md
     - Licence: licence.md
-#  - 'test.md'