[Docs] Initial implementation of py.cafe into the docs

[maxschulz-COL]

Description

• Updates to install page to explain that you can work with Vizro without installing it
• Updates to first tutorial page where it is shown in an iframe
• Explore Vizro tutorial page where it's added to each code block to pass readers through. The final completely worked-up dashboard is also included.

Actions

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

• [ ] 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?
  • [ ] For card-button.md I need to replace relative links to africa.svg and hypotheses.svg: where are they?

• [ ] 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.

• [ ] 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 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 could possibly be resolved by loading from an absolute URL if we store the file first.

• [ ] 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

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

• [ ] 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

• [x] 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

[stichbury]

This is what I've decided wrt annotations in comments:

I have moved small/simple code annotations into inline comments Where there are more chunky comments I have left them as annotations (e.g. the data manager examples) because @huong-li-nguyen said she quite liked it.

If we later work out a fix (or Maarten does) we still have them ready to go, and if not, it's a reasonable workaround. I think.

[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: https://github.com/py-cafe/mkdocs-pycafe/issues/3

[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: https://github.com/py-cafe/mkdocs-pycafe/pull/5

[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! https://github.com/mckinsey/vizro/issues/630