Build multiple versions of documentation

ns-rse commented 1 year ago

I've recently worked out how to build multiple versions of documentation, including API references and host it on GitHub.

As Clarity is now has several versions released and is starting to undergo refactoring I think it would be useful if it adopted multiple versions of documentation rather than always being built off of the HEAD of the main branch as is the current situation.

groadabike commented 1 year ago

Yeah, this would be great. And we need to add the link to documentations in the README

jonbarker68 commented 1 year ago

Great. That would indeed be really useful. If not least for ourselves to more easily keep track of progress as we improve the API;

Thanks

On Fri, 21 Apr 2023 at 12:06, Gerardo Roa Dabike @.***> wrote:

Yeah, this would be great. And we need to add the link to documentations in the README

— Reply to this email directly, view it on GitHub https://github.com/claritychallenge/clarity/issues/305#issuecomment-1517660272, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACO7SJDSOY2RJX3GZLDMDWLXCJS2FANCNFSM6AAAAAAXGUR5HU . You are receiving this because you are subscribed to this thread.Message ID: @.***>

-- Professor Jon Barker, Department of Computer Science, University of Sheffield +44 (0) 114 222 1824

ns-rse commented 1 year ago

Cool, I'll look at getting that done early next week. I've done it once and am going through the process of documenting it so I've a reference to work against and will test it out, correcting anything I've gotten wrong (as I'm doing the documentation retrospectively rather than when I was working things out).

ns-rse commented 1 year ago

And we need to add the link to documentations in the README

I've just added a link to the right-hand sidebar on the repos front page but will check and ensure its present in the README.md too.

ns-rse commented 1 year ago

Tasks to complete....

[x] Add package dependencies to pyproject.toml
[x] Include autoapi.extension and sphinx_multiversion packages in the extensions section of docs/conf.py.
[x] Configure sphinx-apiauto in docs/conf.py.
[x] Configure sphinx-multiversion in docs/conf.py, including html_sidebars = {"**": [ "versioning.html"],}
[x] Add _template/versioning.html for version sidebar.
[x] Update .github/workflows/sphinx_docs_to_gh_pages.yaml to work with multiversion of ns-rse/action-sphinx-docs-to-gh-pages@main.

ns-rse commented 1 year ago

Currently half-way through this.

Some of the documentation versions build but for some tags there are errors thrown by sphinx-multiversion...

❱ sphinx-multiversion docs/ docs/_build/html --dump-metadata
Failed load config for refs/tags/v0.1.0 from /tmp/tmpdi_151jw/d5fe105bfa303c0fda54ce3890930459e4a1546b/docs
Failed load config for refs/tags/v0.1.1 from /tmp/tmpdi_151jw/5a25d417b251989725b7f1645744b133f607887c/docs
Failed load config for refs/tags/v0.2.0 from /tmp/tmpdi_151jw/948f32eeb80cef4014107fad8cb3608da305ad67/docs
Failed load config for refs/tags/v0.2.1 from /tmp/tmpdi_151jw/9bddec01884f4ac8a74f12a3d45c45c12ef526fc/docs
{
  "main": {
    "name": "main",
    "version": null,
    "release": "",
    "is_released": false,
    "source": "heads",
    "creatordate": "2023-04-19 12:37:03 +0000",
    "basedir": "/tmp/tmpdi_151jw/c1147ce61f8f06561611241d6181f4d1824bfb31",
    "sourcedir": "/tmp/tmpdi_151jw/c1147ce61f8f06561611241d6181f4d1824bfb31/docs",
    "outputdir": "/home/neil/work/projects/claritychallenge/clarity/docs/_build/html/main",
    "confdir": "/tmp/tmpdi_151jw/c1147ce61f8f06561611241d6181f4d1824bfb31/docs",
    "docnames": [
      "CODE_OF_CONDUCT",
      "CONTRIBUTING",
      "recipe_rsync_exclude",
      "usage",
      "installation",
      "introduction",
      "recipes_doc",
      "index"
    ]
  },
  "v0.3.0": {
    "name": "v0.3.0",
    "version": null,
    "release": "",
    "is_released": false,
    "source": "tags",
    "creatordate": "2023-03-31 16:39:47 +0100",
    "basedir": "/tmp/tmpdi_151jw/61ba51371499148ad3d13ea9df7d8ef56a0c441a",
    "sourcedir": "/tmp/tmpdi_151jw/61ba51371499148ad3d13ea9df7d8ef56a0c441a/docs",
    "outputdir": "/home/neil/work/projects/claritychallenge/clarity/docs/_build/html/v0.3.0",
    "confdir": "/tmp/tmpdi_151jw/61ba51371499148ad3d13ea9df7d8ef56a0c441a/docs",
    "docnames": [
      "CODE_OF_CONDUCT",
      "CONTRIBUTING",
      "recipe_rsync_exclude",
      "usage",
      "installation",
      "introduction",
      "recipes_doc",
      "index"
    ]
  },
  "v0.3.1": {
    "name": "v0.3.1",
    "version": null,
    "release": "",
    "is_released": false,
    "source": "tags",
    "creatordate": "2023-04-21 10:10:33 +0100",
    "basedir": "/tmp/tmpdi_151jw/f6d0f660516a4baf62ebfc18e0cc747aaf681686",
    "sourcedir": "/tmp/tmpdi_151jw/f6d0f660516a4baf62ebfc18e0cc747aaf681686/docs",
    "outputdir": "/home/neil/work/projects/claritychallenge/clarity/docs/_build/html/v0.3.1",
    "confdir": "/tmp/tmpdi_151jw/f6d0f660516a4baf62ebfc18e0cc747aaf681686/docs",
    "docnames": [
      "CODE_OF_CONDUCT",
      "CONTRIBUTING",
      "recipe_rsync_exclude",
      "usage",
      "installation",
      "introduction",
      "recipes_doc",
      "index"
    ]
  }
}

Digging down it appears such errors have cropped up before (e.g. this and this and have been addressed).

I think its because for some reason the docs/conf.py in the branch/tag can not be found, but adding some debugging to sphinx_multiversion.main.load_sphinx_config_worker() which makes the call sphinx.config.Config.read() the file does exist under all branches/tags for which attempts are made to build the documentation...

❱ sphinx-multiversion docs/ docs/_build/html --dump-metadata

/home/neil/work/projects/claritychallenge/clarity/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True

/tmp/tmp5sfm9wid/c1147ce61f8f06561611241d6181f4d1824bfb31/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True

/tmp/tmp5sfm9wid/d5fe105bfa303c0fda54ce3890930459e4a1546b/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True
Failed load config for refs/tags/v0.1.0 from /tmp/tmp5sfm9wid/d5fe105bfa303c0fda54ce3890930459e4a1546b/docs

/tmp/tmp5sfm9wid/5a25d417b251989725b7f1645744b133f607887c/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True
Failed load config for refs/tags/v0.1.1 from /tmp/tmp5sfm9wid/5a25d417b251989725b7f1645744b133f607887c/docs

/tmp/tmp5sfm9wid/948f32eeb80cef4014107fad8cb3608da305ad67/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True
Failed load config for refs/tags/v0.2.0 from /tmp/tmp5sfm9wid/948f32eeb80cef4014107fad8cb3608da305ad67/docs

/tmp/tmp5sfm9wid/9bddec01884f4ac8a74f12a3d45c45c12ef526fc/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True
Failed load config for refs/tags/v0.2.1 from /tmp/tmp5sfm9wid/9bddec01884f4ac8a74f12a3d45c45c12ef526fc/docs

/tmp/tmp5sfm9wid/61ba51371499148ad3d13ea9df7d8ef56a0c441a/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True

/tmp/tmp5sfm9wid/f6d0f660516a4baf62ebfc18e0cc747aaf681686/docs/conf.py
os.path.isfile(confpath/conf.py) ???? : True

I'll continue to try and get this working though.

ns-rse commented 1 year ago

Not the only the underlying cause of these failures.

Older releases do not have the version specified in the docs/conf.py, instead its empty with version = "". Didn't start automatic versioning until v0.3.0.

I've queried if this may be the root cause and hope to receive some advice on resolving it.

claritychallenge / clarity

Build multiple versions of documentation #305