Documentation site

[amanji]

This PR adds a doc site (built with Docusaurus) to ACA-Py. RTD files have been moved into a subfolder of docs and Sphinx-generated .rst files are converted to markdown to be included in docs.

[swcurran]

I don't think we can merge this as the move of the RTD docs will break the RTD site we have. We need to rethink how we are adding generated site support to the repo.

[swcurran]

@amanji -- what is needed to get this merged? Here are the questions/confirmations I have:

1. The RTD generated folder is currently manually maintained -- e.g. the files in the folder are produced locally (via a couple of commands) and then a PR created with any updates. In theory that could be done via a GHA, but in my experience, with that type of thing, it's a bit of pain, and might make the current ReadTheDocs generation difficult. I suggest that we leave it as is for now, at least until we deprecate and eliminate the current readthedocs site.

2. You need to clean up the problematic docstrings in the code -- the use of <>s. At some point, we want to add a check for that in a PR test, but not needed yet.

3. Why are the "assets" eliminated? Those are currently being referenced in the MD files in the root folder, I believe. I believe they are needed and if you move them, you need to update the MDs that reference them, so they don't break.

Are there any other things needed? Once we've merged this, we can launch the gh-pages site and iterate on it, right?

[amanji]

• The Docusaurus flow should, in theory, not break the current RTD, so I'll leave those generated .rst files as is and we can update them manually for safety.
• Working on a Remark/Rehype plugin to fix the problematic markdown
  • This may take a bit more time so will use an external link to get things moving along
• Assets were accidentally removed, will add those back and update the links as needed
• Adding an example of a version dropdown
• Re-add the homepage components back (will leave out the images for now)

Once the PR is merged we simply need to enable GH Pages to be deployed from a branch (this will be in the repo settings) the branch should be set to gh-pages and from there it's all automatic.

[swcurran]

I accidentally ran yarn at the root level instead of the docs level. Is it worth putting the .gitignore entries at a higher level? No problem if inappropriate, but wondered.

Other than that, looks good. I will amp up the how to run locally documentation -- it's bare, but I got through it. Had some fun on Ubuntu with node versions, what to upgrade to and so on. Then had finding authoritative information on installing/updating and what versions of node both worked and ran on my system. Finally, had a weird error about number of "watchers" parameter in my Linux config that I had to fix. Fun stuff.

Let me know if you think the gitignore is worth doing and then I will merge when I have a next chance to look at it.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[amanji]

Will re-open once local testing complete