DOC: auto-generate and deploy API documentation via sphinx and github pages

[Sheila-nk]

• Configured Sphinx to read and build scipy_doctest documentation, including the README and extracting docstrings from the plugin, frontend and impl modules.
• Implemented a GitHub Actions workflow to automate the build and deployment of documentation to GitHub Pages.

[Sheila-nk]

• Import the project to ReadTheDocs: RTD tutorial.

@ev-br Kindly help with this step. I can only grant access to my forked repository.

Also, could you specify which other modules' docstrings need to be autogenerated on RTD? Maybe the frontend and impl modules as well? I will add missing docstrings to some classes and functions for complete documentation.

[ev-br]

This is great Sheila, thank you for starting this!

1. What do I need to do to enable RTD here?
2. Speaking of RTD or ReST vs markdown --- might be a good idea to check with @lucascolley how he does the docs in https://github.com/data-apis/array-api-extra

---

For what do document :

• we definitely want a docstring of DTConfig and other DT* classes (those can be short and say that these are drop-in replacements of the standard library doctest analogs modulo a DTConfig argument);
• in frontend.py, we very much want find_doctests, the rest of frontend.py could be a nice addition.

In a follow-up, after the bulk of the transition is done, it'd be nice to split the current README into logical bits. No need to worry about it just yet though.

[lucascolley]

The docs process for array-api-extra is:

• all written in plain markdown with furo theme
• using various extensions to enable .. autosummary for the API reference (I'm not sure if every extension is used - I think sphinx.ext.napoleon is the one that renders the docstrings)
• docs task: docs = { cmd = "sphinx-build . build/", cwd = "docs" }
• docs-build workflow runs the docs task and uploads the artefact on every PR
• docs-deploy workflow publishes the artefact on GitHub Pages on every commit to main

I think it should be relatively simple to swap out the GitHub Pages part for Readthedocs - I was going to use RTD initially, but for array-api-extra it was more simple to piggyback off the existing data-apis setup for Pages

[Sheila-nk]

What do I need to do to enable RTD here?

You'd need to create a Read the Docs account, then click on the Import a Project button on your dashboard to import scipy_doctest to RTD.
RTD will then build the project documentation since I have configured Sphinx and RTD on the repo.

[Sheila-nk]

Thanks, @lucascolley! That’s really helpful.

I think using parser extensions is a better approach for building our documentation, especially since we started with markdown, there’s no need to change it. Plus it is easier to learn and use.

For scipy_doctest, hosting the docs on RTD seems like the best option since it automates builds and deployments on each pull request and push, eliminating the need for additional workflows.

[ev-br]

I'd actually suggest we try replicating the array-api-extra setup. Would you give it a go Sheila?

[Sheila-nk]

@lucascolley
I'm encountering deployment issues. Did you need to configure any additional settings to enable GitHub Pages deployment?

[lucascolley]

That may well be the case, yes, I think the data-apis org already had an existing setup on which to piggyback. @ev-br I suppose you should have permissions for whatever is needed here?

[ev-br]

I toggled to publish from the main branch's / (root). Do let me know what other switches are needed!

[Sheila-nk]

Hi @ev-br 👋
I came across this discussion while troubleshooting. Could you please confirm that the following steps have been completed?

• Ensure that your workflow permissions are set to Read and Write. Go to Settings > Actions > General and enable "Read and write permissions" for the workflow. Without this, the action cannot push to gh-pages.
• Verify that you’ve correctly set your GitHub Pages source. Even if you’re using a GitHub Action, you must choose the “Deploy from a branch” option in Settings > Pages and select the gh-pages branch that the action deploys to. The github-pages-deploy-action updates that branch, and GitHub Pages uses that branch to serve your site.

[ev-br]

Permissions:

Deploy from a branch: is set to deploy from main. Should it be some other branch?

[Sheila-nk]

I think all the settings are okay. Let me run the workflow to test.