From c654eabc202709e126d13028a982151a7ca98440 Mon Sep 17 00:00:00 2001 From: James Tocknell Date: Thu, 11 Jul 2024 23:28:43 +1000 Subject: [PATCH] Try to get the both online sphinx docs working Readthedocs and doctr seem to no longer work. Redo the readthedocs version by not including package as a dependency, redo API version using normal git with github-pages branch on CI. --- .github/workflows/test-overall.yml | 2 +- .readthedocs.yaml | 6 +---- apidocs/api.rst | 4 ++-- apidocs/conf.py | 4 +++- apidocs/requirements.txt | 2 ++ apidocs/upload_api_docs.sh | 19 +++++++++++++++ docs/conf.py | 22 ++++++++++------- packages/scikits-odes/src/scikits/odes/ode.py | 2 +- packages/scikits-odes/src/scikits_odes/dae.py | 6 ++--- tox.ini | 19 ++++++--------- upload_api_docs.sh | 24 ------------------- 11 files changed, 52 insertions(+), 58 deletions(-) create mode 100755 apidocs/upload_api_docs.sh delete mode 100755 upload_api_docs.sh diff --git a/.github/workflows/test-overall.yml b/.github/workflows/test-overall.yml index 99dcfbba..26070692 100644 --- a/.github/workflows/test-overall.yml +++ b/.github/workflows/test-overall.yml @@ -42,7 +42,7 @@ jobs: sundials-index-size: 64 - python-version: "3.11" sundials-version: "6.5.0" - tox-env: doctr + tox-env: apidocs-deploy sundials-precision: double sundials-index-size: 64 - python-version: "3.11" diff --git a/.readthedocs.yaml b/.readthedocs.yaml index cd6d163f..51515ece 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,13 +6,9 @@ version: 2 # Set the OS, Python version and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-lts-latest tools: python: "3.11" - # You can also specify other tool versions: - # nodejs: "19" - # rust: "1.64" - # golang: "1.19" # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/apidocs/api.rst b/apidocs/api.rst index 2136b3d6..f93010ff 100644 --- a/apidocs/api.rst +++ b/apidocs/api.rst @@ -8,12 +8,12 @@ scikits.odes scikits.odes.ode ---------------- .. automodule:: scikits.odes.ode - :members: OdeBase + :members: scikits.odes.dae ---------------- .. automodule:: scikits.odes.dae - :members: DaeBase + :members: scikits.odes.dopri5 -------------------- diff --git a/apidocs/conf.py b/apidocs/conf.py index de3cbc26..1ad0e02e 100644 --- a/apidocs/conf.py +++ b/apidocs/conf.py @@ -35,11 +35,13 @@ 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', + 'docs_versions_menu', + 'sphinxcontrib.jquery', ] intersphinx_mapping = { 'scipy': ( - 'https://docs.scipy.org/doc/scipy/reference/', None + 'https://docs.scipy.org/doc/scipy/', None ) } diff --git a/apidocs/requirements.txt b/apidocs/requirements.txt index a6ac0a34..88089024 100644 --- a/apidocs/requirements.txt +++ b/apidocs/requirements.txt @@ -1,2 +1,4 @@ sphinx>=1.4 sphinx_rtd_theme +sphinxcontrib-jquery +docs-versions-menu diff --git a/apidocs/upload_api_docs.sh b/apidocs/upload_api_docs.sh new file mode 100755 index 00000000..382b4430 --- /dev/null +++ b/apidocs/upload_api_docs.sh @@ -0,0 +1,19 @@ +#!/bin/sh + +set -ex + +# Clone gh-pages +git clone --branch gh-pages https://github.com/bmcage/odes gh-pages +# Run rsync +branch_name="$GITHUB_REF_NAME" +rsync -av --delete "$API_DOCS_OUT_DIR" "./gh-pages/$branch_name/" +# Run docs-versions-menu +cd gh-pages +docs-versions-menu +# Commit and push +git config user.name github-actions +git config user.email github-actions@github.com +git add -A --verbose +git status +git commit --verbose -m "Auto-update from Github Actions Workflow" -m "Deployed from commit ${GITHUB_SHA} (${GITHUB_REF})" +git push --verbose --force "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/bmcage" gh-pages diff --git a/docs/conf.py b/docs/conf.py index 3b00f7fc..37fc351e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,13 +12,19 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import subprocess + +try: + sk_version = subprocess.run( + ["git", "describe", "--tags", "--dirty", "--always"], + capture_output=True, + check=True, + text=True, + ).stdout.strip() +except: + sk_version = os.environ["SCIKITS_ODES_VERSION"] -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -import scikits.odes # -- General configuration ------------------------------------------------ @@ -39,7 +45,7 @@ intersphinx_mapping = { 'scipy': ( - 'https://docs.scipy.org/doc/scipy/reference/', None + 'https://docs.scipy.org/doc/scipy/', None ), 'apidocs': ( 'https://bmcage.github.io/odes/dev', None @@ -67,9 +73,9 @@ # built documents. # # The short X.Y version. -version = scikits.odes.__version__ +version = sk_version # The full version, including alpha/beta/rc tags. -release = scikits.odes.__version__ +release = sk_version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/packages/scikits-odes/src/scikits/odes/ode.py b/packages/scikits-odes/src/scikits/odes/ode.py index 97e0d87e..493d2b5d 100644 --- a/packages/scikits-odes/src/scikits/odes/ode.py +++ b/packages/scikits-odes/src/scikits/odes/ode.py @@ -1,2 +1,2 @@ # Compat with older versions -from scikits_odes.odes import * +from scikits_odes.ode import * diff --git a/packages/scikits-odes/src/scikits_odes/dae.py b/packages/scikits-odes/src/scikits_odes/dae.py index e4288d91..3c7a65e3 100644 --- a/packages/scikits-odes/src/scikits_odes/dae.py +++ b/packages/scikits-odes/src/scikits_odes/dae.py @@ -58,10 +58,8 @@ class dae(object): x : independent variable, eg the time, float y : array of n unknowns in x yprime : dy/dx array of n unknowns in x, dimension = dim(y) - return_residual: array that must be updated with the value of the - residuals, so G(t,y,y'). The dimension is equal to dim(y) - return value: integer, 0 for success. It is not guaranteed that a solver - takes this status into account + return_residual: array that must be updated with the value of the residuals, so G(t,y,y'). The dimension is equal to dim(y) + return value: integer, 0 for success. It is not guaranteed that a solver takes this status into account Some solvers will allow userdata to be passed to eqsres, or optional formats that are more performant. diff --git a/tox.ini b/tox.ini index 3b411766..91922049 100644 --- a/tox.ini +++ b/tox.ini @@ -23,33 +23,28 @@ deps = notebooks: nbval notebooks: -r notebook-requirements.txt commands = - env + env | sort test: pytest --pyargs scikits.odes --pyargs scikits_odes --pyargs scikits_odes_core --pyargs scikits_odes_daepack --pyargs scikits_odes_sundials {posargs} notebooks: pytest --nbval ipython_examples/ -[testenv:doctr] +[testenv:apidocs] passenv=* +setenv= + API_DOCS_OUT_DIR={envtmpdir}/html deps= packages/scikits-odes packages/scikits-odes-core packages/scikits-odes-daepack packages/scikits-odes-sundials - doctr - jinja2 -rapidocs/requirements.txt commands= - env - ./upload_api_docs.sh -changedir = - {toxinidir} + sphinx-build -W -b html -d {envtmpdir}/doctrees . {env:API_DOCS_OUT_DIR} + upload: ./upload_api_docs.sh +changedir=apidocs [testenv:docs] changedir=docs deps= - packages/scikits-odes - packages/scikits-odes-core - packages/scikits-odes-daepack - packages/scikits-odes-sundials -rdocs/requirements.txt commands= sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html diff --git a/upload_api_docs.sh b/upload_api_docs.sh deleted file mode 100755 index f44688c3..00000000 --- a/upload_api_docs.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/bin/sh - -set -e - -if [ "$GITHUB_REPOSITORY" = "bmcage/odes" ] || [ "$DOCTR_DEPLOY" ]; then - deploy="true" -else - deploy="false" -fi - - -if [ "tag" = "$GITHUB_REF_TYPE" ]; then - DEPLOY_DIR=dev; -else - DEPLOY_DIR="version-$GITHUB_REF_NAME"; -fi - -make -C apidocs html - -if [ $deploy = "true" ]; then - doctr deploy --no-require-master --build-tags --command "$VIRTUAL_ENV/bin/python build_index.py" --built-docs apidocs/_build/html "$DEPLOY_DIR" -else - echo 'Not deploying docs, set DOCTR_DEPLOY to do deployment of docs' -fi