[Docs] Add py.cafe to the docs examples

[maxschulz-COL]

READY FOR REVIEW!

Description

• There's a PR against the plugin to make the link to py.cafe more visible (bold text, maybe add an icon)

  • See here

• Where images are used in dashboard examples, we need to link to their locations with absolute URLs. We currently have them hard-coded to an assets folder but that doesn't work for py.cafe since everything is uploaded to projects in a single root folder. Some of the commentary around the example needs changing to accommodate the new link location too:

  • For explore-components.md I need to replace relative links to collections.svg and features.svg: where are these files?
    • I found these in vizro-internal and added them to this PR so we can use the raw GitHub hosted URL
  • For card-button.md I need to replace relative links to africa.svg and hypotheses.svg: where are they?
    • For some of these examples I needed custom CSS in the assets folder so I made projects to host these and linked through to them. The assets are stored in GitHub too in case we ever need them again.

• I don't think it works to put the iframe inside the tabbed code block. We could include the embed below perhaps, but I suggest we remove it except for the simplest case in the quickstart dashboard, which is OK.

• The code links in figure.md "How to use figures" are hard to spot because there are some footnotes that come below them. There's possibly a better way to structure these notes, though I appreciate they only apply to the pydantic code so can't be placed below the entire block.

  • I resolved this by adding as comments in the code. Sure, we lose some links but I think our readers will find the reference from the links given in the text already.

• In navigation.md there are snippets of code in the examples except the first (see here) and I'm wondering if we should add an extra tab to these to share them as complete examples...or leave as an exercise for the reader?

  • I added them (made the original code called snippet.py and added app.py for each)

• I didn't make changes to assets.md code snippets because this relies on having access to the assets folder which doesn't work on py.cafe.

• Same for data.md which loads iris.csv but this I resolved this by generating the data as px.data.iris()

• Chain actions example on actions.md doesn't work here -- error in py.cafe: ModuleNotFoundError: You must install either openpyxl or xlsxwriter to export to xlsx format.

• The above error also occurs in the first example in custom_actions.md

• In custom_components.md there are line number highlights and expanders in the code example, see here which don't work with the mkdocs plugin. @maxschulz-COL is going to take a look at this one.

  • Update to add: we haven't been able to resolve the expanded annotations so we are leaving them as is for now because they render to numbered references/footnotes to the code examples, which look OK.

• In custom_components.md there is an image needed for the carousel here

  • I fixed this by creating a custom example which hosts the graphics but also added copies into GitHub in case they're needed later

• Final example on custom_figures doesn't look like the screenshot

Updates needed for screenshots:

• Sunburst on pages.md is now blue throughout -- no red colour

Original POC description

This is a first POC of how we could integrate py.cafe into the docs. Atm the PR just contains two implementation version, but there will be more added later on:

1. First tutorial page - simple iframe not even tabbed, just let the app with appropriate links speak for itself
2. Explore Vizro tutorial (first code example) - as part of a tabbed view, using the hosted screenshot, and the app in different tabs

Other future options will be:

• having also the code editor embedded
• having the code displayed from a single source

Screenshot

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.

[stichbury]

This is fantastic: the future is here! I would definitely like to see the code included, and the idea of single source code sounds best of course. Looking forward to seeing this progress 🚀

[stichbury]

@maxschulz-COL Now I've returned, do you want me to pick this up in the coming sprint?

[maxschulz-COL]

@maxschulz-COL Now I've returned, do you want me to pick this up in the coming sprint?

Yes that would be amazing! I have a few new ideas here - so we should probably sync mid-week to get this done. But definitely worthwhile scheduling some time in this sprint

[maartenbreddels]

If we later work out a fix (or Maarten does)

What does not work as expected?

[stichbury]

If we later work out a fix (or Maarten does)

What does not work as expected?

You're keeping tabs on us :) It's the issue with annotations in the code. Let me link you to the thread...

[stichbury]

@maartenbreddels

Let me link you to the thread...

I couldn't find it so I've recreated it here. We use annotations in some of our code snippets. This page is a good example: https://vizro.readthedocs.io/en/stable/pages/user-guides/data and here's a screenshot:

But when the plugin is activated for pycafe, this doesnt work and the comments render as specified:

@maxschulz-COL has investigated but we haven't put too much time in as most of our examples look fine without the annotation (and the data manager examples don't use py.cafe at present for another, different reason). But what do you think? Any ideas on how to enable the mkdocs annotation plus pycafe plugin together?

[maxschulz-COL]

If we later work out a fix (or Maarten does)

What does not work as expected?

I raised an issue in the repo: py-cafe/mkdocs-pycafe#3

[huong-li-nguyen]

LGTM 👍

Pre-approval assuming we come up with some conclusion on the code annotations. Have a general question whether we should actually store the py.cafe doc examples in a vizro py.cafe profile, as otherwise we'll have a collection of examples living in several profiles. Might be better to have one profile to which everyone has access to and can edit it 👍

[maxschulz-COL]

LGTM 👍

Pre-approval assuming we come up with some conclusion on the code annotations. Have a general question whether we should actually store the py.cafe doc examples in a vizro py.cafe profile, as otherwise we'll have a collection of examples living in several profiles. Might be better to have one profile to which everyone has access to and can edit it 👍

I think that is a great idea - could we even create one with our vizro email?

[huong-li-nguyen]

I think that is a great idea - could we even create one with our vizro email?

Yes, that was what I was thinking :) Use our vizro service account email 👍

[stichbury]

I think that is a great idea - could we even create one with our vizro email?

Yes, that was what I was thinking :) Use our vizro service account email 👍

See my comment here. It's a great idea but too late for implementation (by me) this time. Can we do this when we next update example code?

[maartenbreddels]

Code annotations should work now: py-cafe/mkdocs-pycafe#5

[maxschulz-COL]

Cannot approve my own PR, but just wanted to say: Absolutely amazing rework. 🚀 ⭐ 🙏

I left minor comments that we can also ignore for now, but that can serve as a reminder.

[stichbury]

Approving for @maxschulz-COL after final commit on those comments.

[stichbury]

Phew, that was a mammoth PR! Thanks @huong-li-nguyen @maartenbreddels and @maxschulz-COL for getting it over the line.

Here's the follow up issue and feel free to add anything else I've forgotten! #630