POC for documentation using typedoc and sphinx-js

[hemant-hc]

This POC uses typedoc and sphinx-js to generate documentation.

We need to specify the version of sphinx related packages in the constraints file because when the versions are not specified sphinx-js 1.0 is auto-installed, which is far older than the latest version 3.2.1, and lacks many of the features.

Sphinx-js supports a super old typedoc version 0.15.0 officially at least and I encountered another typedoc problem related to type errors reported in node_modules (which doesn't work even with --skipLibCheck for some reason) as well in my POC.

I think we can get it to work but it will require significant amount of time to debug and fix. Even then we might face issues with using latest typescript and typedoc. Perhaps it's better to just use latest typedoc with something like docusaurous?"

[hemant-hc]

@sneridagh @stevepiercy I encountered some issues while making this POC, I have mentioned them in detail in the PR description.

[sneridagh]

Maybe there's a more up to date plugin for sphinx...

[stevepiercy]

There's also a dependency conflict over Sphinx, even when I try to install sphinx-js from a fork by the Pyodide team.

$ bin/pip install git+https://github.com/pyodide/sphinx-js.git@master

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
myst-parser 2.0.0 requires sphinx<8,>=6, but you have sphinx 5.3.0 which is incompatible.
Successfully installed Sphinx-5.3.0 markupsafe-2.0.1 parsimonious-0.10.0 pydantic-1.10.12 regex-2023.8.8 sphinx-js-3.2.1

There are a few open issues and PRs on the sphinx-js project that indicate there is interest in its further development. There's been a fork, too.

• Fix support for typedoc 0.19 mozilla/sphinx-js#219
• Fork sphinx-js pyodide/pyodide#3549
• Some todos pyodide/sphinx-js-fork#26

It was worth a shot. Thank you for trying @hemant-hc.

It's OK to close this PR, or leave it open to get more exposure.