[Docs] Rewrite run methods and deployment docs

[stichbury]

Description

@stichbury started reorganising and tidying the "Run methods" page, and @antonymilne extended the changes to rewrite much of it from scratch. This was probably the weakest part of our docs before and it's hopefully much improved now.

Reviewers: don't try to look at the diff, just look at the built docs:
These are waiting for a fix to keep linkchecker quiet -- you can build locally and look at the run-deploy page at present.

https://vizro--945.org.readthedocs.build/en/945/pages/user-guides/run/
https://vizro--945.org.readthedocs.build/en/945/pages/user-guides/deploy/

Major changes:

• split the run page into two: "How to run your dashboard in development" and "How to deploy your dashboard to production". We don't use the word "launch" any more (although I don't hate the word, so feel free to still say it where it makes sense!)
• content of the run page is largely the same as before but reorganised
• deploy page is completely new. We have detailed sections on Hugging Face, Ploomber, Dash Enterprise, plus general guidance on other solutions
• Ploomber instructions summarise and refer to our new section in their documentation (FYI @edublancas)
• Hugging Face instructions follow a whole new method that is basically "one click". I have created a new demo dashboard in our gallery for this
• Updated all our official Vizro demo dashboards on HF to simplify the Dockerfile and use uv

TODO:

• @maxschulz-COL to fix docs build - seems to be failing due to HF gallery links
• @maxschulz-COL to review, complete TODOs left in the docs and then merge when ready.
• @maxschulz-COL to create non urgent new tickets:
  • get Vizro added as a full template in HF if feasible in future
  • get Vizro added as a full template in Ploomber if feasible in future
• @maxschulz-COL once PR has merged and docs are released, edit https://huggingface.co/spaces/vizro/demo-first-dashboard/blob/main/README.md to refer back to the deploy page of the docs so users can follow the tutorial

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[github-actions]

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2025-02-07 13:54:01 UTC
Commit: bac91a2

Link: vizro-core/examples/dev/

Link: vizro-core/examples/scratch_dev

Link: vizro-core/examples/visual-vocabulary/

Link: vizro-ai/examples/dashboard_ui/

[petar-qb]

Really great refactoring 👍

I have a question: should the Gunicorn section go under deployment? It mentions deployment so naturally would fit better, right?

I agree that the "Gunicorn" section should go under the "Deployment". Great spot!

Also, and maybe related, I am concerned that we aren't that tight about language, or maybe it's my understanding. The file is called run.md and the ToC had the page listed as "Run methods" but we mostly talk about "launching" and then Gunicorn talks about deployment, then there's a section on deployment. Can I get clarity on the difference, or not, in what we mean by "run", "launch" and "deploy" and then I'll run through again and ensure everything is consistent.

I understand the confusion because these terms are quite intertwined here.
So, "run" and "launch" are the same terms that describe running/launching the app locally (for the development purpose).
However, deployment means more like setting-up and running the production-ready app somewhere on the server (not locally).

Also, I like the "Launch the dashboard" title, and also the suggestion to move "Gunicorn" under the "Deployment" section. I guess we should rename the file from run.md -> launch_the_dashboard.md, and align wordings across documents accordingly.

[stichbury]

Thanks @petar-qb, that's really helpful feedback!