Automatic Library Docs

[matthewkaney]

Per some of the discussion in this Tidal Club post, I had a bit of downtime and wrote up a parser for Haddock HTML -> MDX. The custom parser scares me a bit, but I think it's ultimately better than an automated solution (eg Pandoc), because it allows us to better extract the specific context from the Haddock doc page.

TODOS:

• Build a Github Action to rebuild this documentation (presumably when tidalcycles/Tidal publishes a new release) and submit the changes to this repository as a pull request (so it can be manually updated)
• Specify the template that Haddock uses, so that docs generated by future versions are (theoretically) backwards-compatible
• Implement more aspects of Haddock comments (headers, types/constructors/classes)
• Fuss with styling, and add custom components for things like type signatures (which are like code blocks, but with hyperlinked types, etc
• Also generate separate pages (eg "/docs/library/functions/cat") so each function can be nicely permalinked outside of the module structure? Refer to A page for each function #114
• Some sort of generated function index that links to all the functions? Refer to provide index page #70
• Some sort of Github action that flags PRs that try to commit manual changes to the generated documentation

And, of course, add a ton of Haddock documentation/API cleanup to Tidal, but that's out of scope for this PR 😄

I'll keep working on this draft, but it's far enough along that I feel like I should open things up. What do you all think? Is this a good idea? Any opinions on what this section should be called, or how it should be organized? Are there specific bits of metadata that should be included on Module

[jwaldmann]

wrote up a parser for Haddock HTML -> MDX.

Amazing.