Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
For 1.x we should have a documentation strategy beyond publishing our API docs.
How do we want to handle supplemental documentation? Docusaurus? Typedoc plugins? Some use of drupal.org documentation?
Steps to reproduce
Proposed resolution
Possible Drupal.org documentation:
* Examples of common features (link to API docs where possible?)
* Show both TS and JS examples?
* With framework examples - with Next.js, with Astro, etc. Live sandboxes could be useful here.
Other tasks:
* Update Decoupled Router Client readme
Remaining tasks
User interface changes
API changes
Data model changes
Issue fork api_client-3394944
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
changes
Comments
Comment #2
brianperryComment #3
brianperryComment #4
brianperryComment #5
brianperryThis is over the top ambitious, but I'd love to use something like the web containers API https://webcontainers.io/guides/quickstart for interactive examples. It is what Svelte used for their Learn Svelte docs: https://learn.svelte.dev/tutorial/welcome-to-svelte
Comment #6
brianperryI spent some time going through the WebContainers tutorial. Really wild what is possible just within a browser environment - installing node packages, running a server, a fully interactive terminal and live code reload.
I took a quick pass at adapting the tutorial to make a request using the JsonApiClient: https://github.com/backlineint/webcontainers-tutorial Still a lot of work to make that something truly consumable, but think it shows a lot of promise.
As far as what would be next, I think it is trying to come up with a way to include these types of examples in a docs site of some kind. Would it be possible to do this in Docusaurus or Astro Starlight, or would this require us to roll our own somehow.
Also worth pondering if this is still overkill at the end of the day :)
Comment #7
brianperryGiven that our examples aren't all that complicated, I wonder if we could just use the different live code components provided by a popular docs project.
Docusaurus: https://docusaurus.io/docs/markdown-features/code-blocks#interactive-cod...
Astro: https://astro-live-code.mattjennin.gs/
The Docusaurus one is a little flashier, but it is based on React Live, which it seems would limit ourselves to React examples. That alone might make Astro Live Code a better option - it supports any language that Astro supports.
Comment #8
brianperrySeem to be in the docs headspace at the moment, so assigning this one.
Comment #9
coby.sher CreditAttribution: coby.sher as a volunteer commentedOoh exciting! Would there also be a Drupal install in there? Is that practical?
Maybe, but I think it is still worth doing.
Starlight seems like a good option to me!
Comment #10
brianperry> Ooh exciting! Would there also be a Drupal install in there? Is that practical?
Not sure if it is possible. But it likely wouldn't be practical just due to the time it would take to boot.
Comment #12
brianperryMerging to see if we can get the current state of the new docs deployed. Fingers crossed :)
Comment #14
brianperryI don't consider them complete, but we have deployed an initial version of these new docs. I am going to mark this issue as fixed, and then create more specific issues for remaining docs issue.