diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml index cfc45d4..ac6aaeb 100644 --- a/.github/workflows/pypi-release.yml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..85e34f6 --- /dev/null +++ b/.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 diff --git a/docs/developer.md b/docs/developer.md index e1777df..75e23e2 100644 --- a/docs/developer.md +++ b/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 diff --git a/docs/examples/option.md b/docs/examples/option.md index c393792..b3029e6 100644 --- a/docs/examples/option.md +++ b/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]` diff --git a/docs/examples/parallel.md b/docs/examples/parallel.md index 425d43e..ee5ebf8 100644 --- a/docs/examples/parallel.md +++ b/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: diff --git a/docs/examples/src.md b/docs/examples/src.md index e3d0dd4..f9d21e6 100644 --- a/docs/examples/src.md +++ b/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. diff --git a/docs/macros.py b/docs/macros.py index 00a538f..23105b9 100644 --- a/docs/macros.py +++ b/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,6 +15,29 @@ ".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): @@ -20,9 +45,9 @@ def define_env(env): 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() diff --git a/docs/overview.md b/docs/overview.md index d80d69f..b720031 100644 --- a/docs/overview.md +++ b/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. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..2fec029 --- /dev/null +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index a37b7b3..44175a9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,5 +67,4 @@ nav: - Developer: developer.md - Support: support.md - Licence: licence.md -# - 'test.md'