docs: switch from sphinx to zensical

[tmorrell]

❤️ Thank you for your contribution!

Description

Here is a proposed pathway for finally getting the documentation for individual repos (where needed) to work.

You can see the rendered documentation at https://caltechlibrary.github.io/idutils/

It dumps makeTheDocs for a GitHub action-based workflow which should be much more robust. I think this workflow should probably go in the inveniosoftware workflows repo if this approach seems good.

It moves from Sphinx to Zensical and from rst to md. This should be easier to maintain, and nothing in the docs folder should need to be touched on a regular basis.

Claude helped with the styling. It looks nice to me but I have no attachment to any of it. Comments are very much appreciated.

I think it makes sense to merge #145 first, and then I'll rebase putting everything in pyproject.toml

Zensical doesn't have python 3.9 support, so we wouldn't be able to run document building in the CI. I think that's fine since it will run as a separate action.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've added relevant test cases.
• I've added relevant documentation.
• I've marked translation strings.
• I've identified the copyright holder(s) and updated copyright headers for touched files (>15 lines contributions).
• I've NOT included third-party code (copy/pasted source code or new dependencies).
  • If you have added third-party code (copy/pasted or new dependencies), please reach out to an architect on Discord.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.

[tmorrell]

This is now rebased, and I opened a PR to centralize the workflow inveniosoftware/workflows#31

[max-moser]

👍

might be that in other packages we have other entries to update, but nothing that a little sed -e 's/\.rst/.md/g' couldn't solve

[max-moser]

looks like a little guy wearing glasses got sad because he got impaled

[max-moser]

Moving from reStructuredText to MD is a great move IMHO...
I cannot even remember the capitalization in reST, let alone the syntax for an (inline) link.

I suppose that the Python docstrings are still stuck with reST though?
And one of the nicer parts of reST/Sphinx (which we don't really use much these days) is the linking between references like classes and functions in the docstrings and docs; is that somehow possible with Zensical?

[tmorrell]

I think I got all of the reST stuff out of the docstrings. If you see any others let me know, and we can just use markdown there and it should work. I'll do a bit of digging to see if linking is possible.