search

hotwired / turbo

The speed of a single-page web application without having to write any JavaScript
https://turbo.hotwired.dev
MIT License
6.56k stars 415 forks source link

Generate `hotwired/turbo-site` content from `hotwired/turbo` source #997

Open seanpdoyle opened 10 months ago

seanpdoyle commented 10 months ago

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 commented 10 months ago

In the meantime, I've opened https://github.com/hotwired/turbo-site/pull/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 commented 7 months ago

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 commented 4 months ago

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.