Generate hotwired/turbo-site content from hotwired/turbo source

[seanpdoyle]

Since the team's official stance is that end-user facing documentation serves as the project's source of truth (for type information and more), it would be extremely valuable to embed the documentation website into the project's source code.

The documentation pages for Stimulus are generated by commits in the project's docs/ directory. By automatically integrating the two repositories, contributors can propose documentation revisions simultaneously with source code revisions. Without tight integration, it's possible for changes to public interfaces (either through changes to internal JavaScript object properties and functions, Custom Element classes, or changes to CustomEvent.details) to drift from what's documented.

What can be done to enable the same integration and lock step for the Turbo project?

[seanpdoyle]

In the meantime, I've opened hotwired/turbo-site#145 to document CustomEvent type information that was lost with the removal of TypeScript.

Some CustomEvents are dispatched with references to internally defined Turbo JavaScript objects like FormSubmission, FetchRequest, FetchResponse, FrameElement, and StreamElement.

Without providing type information for those objects, they are prone to change shape in a way that has unintended side-effects related to backward compatibility. If the documentation for those classes resided in the same repository as their source code, it would be easier to coordinate changes in both places at once.

[brunoprietog]

I strongly agree with this, is there anything that can be done? Currently there are already several things that have been released and are not documented yet. Having separate repositories I feel exacerbates the problem. @jorgemanrubia @afcapel what do you think?

[seanpdoyle]

What can be done to enable the same integration and lock step for the Turbo project?

@jorgemanrubia @afcapel @kevinmcconnell now that Turbo 8 has been released, I wonder if there's an opportunity to consolidate @hotwired/turbo-site into this repository.