Conversion of User Guide to the SHH stack

[ahopkins]

This brings the User Guide into the sanic repo, and builds it using Sanic, html5tagger, and htmx. It provides:

1. Have an example application running in production to point people towards that is running Sanic
2. Bring the writing of documentation closer to PRs so that we can keep them aligned as changes are made
3. Moves the API docs and the User Guide to a single site
4. Changes to Google style docstrings which are easier for humans to read and maintain (our RST docstrings were a MESS!!)

It is a massive PR, but it is all documentation, and not really a change at that.

[Tronic]

It's a very large diff. Clearly this does something other than html5tagger and htmx? Should also cover msgspec in docs.

Staying unopionated, JS fronts like htmx (with html5tagger) and vue (with msgspec) should probably be left to their separate tutorial pages, rather than discussed in the main guide. The same goes for databases (urgently needed in practice, still with poor async support).

[ahopkins]

It's a very large diff. Clearly this does something other than html5tagger and htmx? Should also cover msgspec in docs.

@Tronic I think you misunderstood what this branch is. It is an attempt to drop sanic-guide and vuepress in favor of dogfooding Sanic. To achieve templating it uses html5tagger. To get a similar crisp navigation feel, it uses htmx. Not sure msgspec plays into this at all.

Staying unopionated, JS fronts like htmx (with html5tagger) and vue (with msgspec) should probably be left to their separate tutorial pages, rather than discussed in the main guide.

No disagreement. Sanic does not take an opinion. But, clearly in building its own site it needs to make some decisions. In the past it was was Sphinx with RTD. Then vuepress with GH. I am proposing a POC for how we can serve https://sanic.dev using Sanic.

This is sort of a FAQ and a turndown for some. I don't think the performance argument is relevant because the check is quite fast.

Make the suggestion and discussion here: https://github.com/sanic-org/sanic-guide. That is somewhat irrelevant since it is a copy/past with changes only to handle a difference in Markdown extras.

The middleware approach works but hasn't ever been quite officially supported. I think we should make it so. On a blueprint level this can come in handy.

Same.

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: -0.261% ⚠️

Comparison is base (47215d4) 88.689% compared to head (e10e4ba) 88.429%.

Additional details and impacted files

@@              Coverage Diff              @@
##              main     #2781       +/-   ##
=============================================
- Coverage   88.689%   88.429%   -0.261%     
=============================================
  Files           92        92               
  Lines         7082      7156       +74     
  Branches      1214      1228       +14     
=============================================
+ Hits          6281      6328       +47     
- Misses         551       574       +23     
- Partials       250       254        +4     

Files Changed	Coverage Δ
sanic/app.py	88.751% <ø> (-0.603%)	⬇️
sanic/application/constants.py	100.000% <ø> (ø)
sanic/application/ext.py	100.000% <ø> (ø)
sanic/application/logo.py	100.000% <ø> (ø)
sanic/application/motd.py	97.849% <ø> (ø)
sanic/application/spinner.py	100.000% <ø> (ø)
sanic/application/state.py	92.187% <ø> (ø)
sanic/blueprint_group.py	100.000% <ø> (ø)
sanic/blueprints.py	89.067% <ø> (-2.676%)	⬇️
sanic/config.py	97.419% <ø> (ø)
... and 14 more

... and 28 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.