Shift BeeWare tutorial to MkDocs

[kattni]

This PR brings the BeeWare Tutorial to MkDocs. Theme and translation tooling is pulling from https://github.com/beeware/beeware-docs-tools. Existing translations have been preserved to best extent possible.

I can address specifics as needed in the review.

PR Checklist:

• All new features have been tested
• All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[mhsmith]

I can't find it now, but I remember that in some previous RST to Markdown conversion (maybe beeware.org), the conversion tool silently ignored unknown RST keywords, e.g. it would convert :keyword:`content` to `content`. Have we taken steps to make sure this doesn't happen again?

[kattni]

@mhsmith The short answer is yes.

The longer answer is that I used Pandoc with custom settings to convert the rST to Markdown as the first pass. However, Pandoc doesn't have any awareness of the plugins and extensions I'm using for various formatting options, so it provides everything in a particular format that doesn't render properly with the MkDocs setup. To deal with this, I wrote a lengthy Python script that uses regex to parse out all of the Pandoc-formatted elements, and convert them to appropriate Markdown. One of the more involved methods in that script specifically targets the rST keyword links, and converts them into the MkDocs Markdown link format. The conversion script was written with Toga et. al. in mind, but is written in a way that works on any Pandoc CommonMark-converted Sphinx-rST documentation.

Once I have the script where I want it, I will be including it in the beeware-docs-tools repo, along with the completed translation-conversion and in-progress docstring-conversion scripts. This inclusion will be for archival purposes only, as once the documentation is shifted to MkDocs, the scripts are no longer needed.

[kattni]

FYI: these translation fixes will not be necessary moving forward. This is due to how I formatted some things at the time that I generated the PO template files, and will not be an issue in the actual workflow.

[freakboy3742]

I've flagged a handful of fairly cosmetic issues, and some content issues in the contribution guide, but otherwise, this is looking great.

The only other thing that stood out - and it's only obvious now because this is a migration of an existing document with existing translations - is that the location of the translation files has changed from /docs/locales to /locales.

There's two issues here:

1. On a project like toga, we probably want to keep the locale data in the docs folder to keep it isolated.
2. On a project like this tutorial - weblate is currently configured with a specific file location. We can update the URL, but updating the file location as well is going to be painful - it would possibly be easier to just rebuild the entire translation. The tutorial is a lot of individual parts to set up, so I'd rather not do that if I can avoid it.

So... can we move the locales directory into docs? I presume this will need a fix in docs-tools...

[freakboy3742]

A handful of minor tweaks found in a final review pass

Given the significance of the change, I'll tag @mhsmith for an additional review to see if he spots anything out of place - but otherwise, I think this is ready to land. Nice work!

[mhsmith]

The rendering looks pretty good; just a few comments:

---

The "BeeWare Tutorial" caption in the left sidebar seems a bit small: it's being overpowered by the Source code and Issues links below it:

---

When scrolling down, the left and right sidebars should keep moving up the screen until the top BeeWare bar is gone. But currently, they stop scrolling when half of the bar is still visible:

Beyond this point, the BeeWare bar scrolls out of view but the left and right sidebars stay in the same place. This leaves an excessive margin above the sidebars, which aggravates the "side navigation almost unusable" issue mentioned in beeware/toga#3719 (comment).

---

In a narrow screen, there are two unlabeled menu buttons:

By comparison, in the current theme the lower button is clearly associated with the site title:

The confusion could also be mitigated by moving the BeeWare logo next to the upper menu button. Maybe it could even move to the left of the button, which would give more continuity between the narrow and wide layouts: the BeeWare logo would remain in the same place while the menu collapses into a button.

---

It would be much easier to discover other issues if I knew how this was done. Can you make a PR in beeware-docs-tools with the current version of the scripts you mentioned above, along with instructions for doing the conversion, in enough detail that someone else could reproduce this PR?

[freakboy3742]

The rendering looks pretty good; just a few comments:

+1 to those notes as problems; not necessarily sold on some of the suggested fixes. We're in an in interesting situation where we are both constrained by what the MkDocs theme makes easy to do, while also maintaining consistency with the Lektor/Bootstrap-based BeeWare website.

In particular, I can see how moving the logo around might not be possible (or plausible) given the other consistencies we're trying to maintain. I agree the existing "secondary docs bar" (with project name and some of the display controls) is a better rendition. I don't know how much work that would be to add into the existing theme, though.

@kattni has some other changes in flight that came from my review notes on the Toga PR (where some of these issues are a little more acute). We can iterate on those design issues there until we get a fix that works.

[kattni]

It would be much easier to discover other issues if I knew how this was done. Can you make a PR in beeware-docs-tools with the current version of the scripts you mentioned above, along with instructions for doing the conversion, in enough detail that someone else could reproduce this PR?

@mhsmith As requested: beeware/beeware-docs-tools#22

[freakboy3742]

I've just forced a rebuild with the latest docs-tools changes; I'm really happy with where this is now, and I think it has addressed all the issues @mhsmith raised.

@mhsmith - leaving for you to give a final confirmation and approval.

[mhsmith]

My previous comments are all resolved. Just one new issue left: the small version of the logo and the the title are vertically misaligned on a wide screen:

By comparison, in the collapsible sidebar on a narrow screen, they look fine:

Also, I don't know if you've already discussed this, but I'm not sure if there's any point in keeping the large logo on the front page at all. It causes an unnecessary discontinuity between the front page and all the others.

[freakboy3742]

My previous comments are all resolved. Just one new issue left: the small version of the logo and the the title are vertically misaligned on a wide screen:

Confirmed I'm seeing this too.

Also, I don't know if you've already discussed this, but I'm not sure if there's any point in keeping the large logo on the front page at all. It causes an unnecessary discontinuity between the front page and all the others.

Yes, it's a discontinuity - but I actually kinda like it. IME, it's common for a homepage to have a different presentation, especially when it comes to brand presentation. For example, https://nytimes.com has a prominent masthead; but individual articles have a much smaller logo display.

[kattni]

The misalignment is due to the expectation of the version number that isn't included on the tutorial. I'll sort it out when the version number is not included.

[kattni]

Fix is here.

[freakboy3742]

I've just forced a rebuild of the tutorial with the new docs-tools, and it looks great... except for the homepage:

It looks like the text is just ever so slightly too big... if I manually tweak the font to be smaller, it's definitely centred. Same behavior on Safari and Chrome.

[mhsmith]

Yes, it's a discontinuity - but I actually kinda like it. IME, it's common for a homepage to have a different presentation, especially when it comes to brand presentation.

OK, fair enough.

It looks like the text is just ever so slightly too big... if I manually tweak the font to be smaller, it's definitely centred.

The font size looks reasonable to me, and regardless of the size, there will always be some titles that wrap. What matters is that it should still be centered whether it wraps or not.

[kattni]

The font size looks reasonable to me, and regardless of the size, there will always be some titles that wrap. What matters is that it should still be centered whether it wraps or not.

We explicitly chose the font size to maintain a single line with the longest title, which is currently "BeeWare Tutorial". I realise there may be longer ones in the future. I've submitted a fix to handle centering wrapped titles on the homepage on wider displays here.

[freakboy3742]

We explicitly chose the font size to maintain a single line with the longest title, which is currently "BeeWare Tutorial". I realise there may be longer ones in the future. I've submitted a fix to handle centering wrapped titles on the homepage on wider displays here.

Completely agreed about centering; but the problem is that the current font size isn't the right size to fit on one line (or, at least, there's some edge case - it evidently worked for you based on your screen shots, but it doesn't fit for me).

[kattni]

I reverted the font size to the size that I had it initially; it stops wrapping at that size. It's in the PR on docs-tools.

[freakboy3742]

Ok - I think we've got the font sizing and centring issues sorted - this is now ready for final review.

[mhsmith]

@freakboy3742: Apparently I don't have write access to this repository, or to the other recently-created repositories: xbuild and beeware-docs-tools.

[freakboy3742]

@mhsmith Apologies for the (oft repeated) oversight - I've added permission groups to beware-tutorial, beeware-docs-tools and xbuild.