Merge pull request #173 from aragilar/fix-api-docs

Try to get the both online sphinx docs working

.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"

.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:

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
 --------------------

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
     )
 }
 

apidocs/requirements.txt

@@ -1,2 +1,4 @@
 sphinx>=1.4
 sphinx_rtd_theme
+sphinxcontrib-jquery
+docs-versions-menu

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

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.

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 *

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.

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