Final steps for shifting beeware.org to MkDocs

[kattni]

What is the problem or limitation you are having?

This issue is to track the rest of the steps needed to take the new website live.

Relevant PRs

Website PRs

These should all be landed anytime before launch.

• Initial PR: Initial step of migration of beeware.org from Lektor to MkDocs #1
• Events post generation updates: Update event text to better reflect number involved, show keynote first. #6
• Header anchors: Add explicit anchors to any headers likely to be linked. #7
• Docs linting: docs-lint passing #8
• rumdl: rumdl passing, enabled on pre-commit. #9
• Translations: Translations for website migration #10
• Initial machine translations: Initial machine translations. #18

Changes to docs-tools before website migration

• Website header migration: Change name of sponsor link in header. beeware-docs-tools#169

Changes to docs-tools for website migration

Must be landed before final launch.

• Website MkDocs migration: Website MkDocs migration beeware-docs-tools#150

Configuration updates for website migration compatibility

Must be landed with docs-tools 150.

• Toga: Tooling/website migration updates toga#4157
  • Restore docs-tools main branch in pyproject.toml.
• Briefcase: Config updates for website migration compatibility. briefcase#2665
  • Restore docs-tools main branch in pyproject.toml.
• Rubicon: Config updates for website migration compatibility. rubicon-objc#709
  • Restore docs-tools main branch in pyproject.toml.
• Tutorial: Config updates for website migration compatibility. beeware-tutorial#57
  • Restore docs-tools main branch in pyproject.toml.

Known outstanding tasks before we can go live

Completed tasks

### **Translations:** - [x] Merge existing translation PO files with updated POT file. - [x] Ensure translation workflow is present in the repo - [x] Ensure translations are all building properly. - [x] Restore full set of translation commands to `tox.ini` - [x] Initial translation pass through DeepL to get machine translation. - [ ] Add translation CI workflow after initial machine translation. - [x] Set up Read the Docs translations for every language. - [x] Set up Weblate: - [x] Add website repo - ~~[ ] Identify strings that do not need to be presented for translation~~. ### **Header anchors:** - PR MERGED - [x] Add explicit anchors to any headers being linked from elsewhere to avoid failures when translating headers. ### **rumdl:** PR MERGED - [x] Work through issues to get rumdl passing - [x] Ensure any rules that are conflicting with MkDocs syntax are disabled in pyproject.toml rumdl configuration ### **Redirects:** - PR MERGED - [x] Grab short URL redirect info from existing site configuration - [x] Add list to configuration. ### **Docs linting:** - PR MERGED - [x] Enable Markdown link checker and PySpelling - [x] Get both passing ### **`.readthedocs.yaml`** - PR MERGED - [x] Remove `--build-with-warnings` ### **`tox.ini`** - Restore full suite of translation commands (as noted above) - [x] Remove `--build-with-warnings` where necessary - Enable linting tools (as noted above)

BeeWare Docs Tools Header rename PR #169

Rebuild stable docs (and any historical docs with a header) for:

• Toga. pending - linting issue due to links on branch
• Rubicon-Objc
• Briefcase pending - linting issue due to links on branch

BeeWare Docs Tools PR #150

• Land the noted PR before everything goes live.

Website PR #21

• Restore beeware-docs-tools main branch in pyproject.toml
• Land Fixes from pre-release feedback. #21

Merge configuration updates on existing docs repos

• Toga
• Briefcase
• Rubicon ObjC
• Tutorial

DNS updates

• Point beeware.org to Read the Docs

[johnzhou721]

Hi -- I see that "set up weblate" is already under completed tasks, so I translated a few strings and then pressed the option to download the PO file on Weblate in order to force a commit to see how it works. However, now it's locked with this message:

The translation is temporarily closed for contributions due to maintenance, please come back later.
The translation was automatically locked due to the following alert:
[Could not push the repository.](https://hosted.weblate.org/projects/beeware/website/#alerts)

https://hosted.weblate.org/projects/beeware/website/#alerts

Sorry for the inconvenience caused here.

[kattni]

@johnzhou721 We're sorting it out. There were a few more steps to be taken to get Weblate fully integrated.

[johnzhou721]

@kattni In that case: Sorry for not knowing the context in this case.

[freakboy3742]

beeware/beeware-docs-tools#169 has been merged. RTD builds for most projects has failed because of linting problems; Rubicon builds succeeded.

The pre-mkdocs-website branch of beeware-docs-tools has the state of the code prior to the merge of beeware/beeware-docs-tools#150.

[freakboy3742]

We performed the DNS switch - and then discovered that because of how RTD deploys pages, https://beeware.org would redirect to https://beeware.org/en/latest - and with that redirect, all the old URLs like https://beeware.org/about would break.

It is possible to configure RTD to a "no translations, no versions" URL configuration; and a "no translations, only versions" URL configuration... but not a "No versions, only translations" configuration - and even then, the base URL would always be /en for the English site.

So - we need to go back to the drawing board for hosting.

I can think of two options:

1. Use beeware.org for the English site, but de.beeware.org for the German site. This would essentially avoid all the language configuration mechanisms on RTD, and require DNS-level configurations for each language. As a follow on, it might be worth reposting the tutorial in the same way (at tutorial.de.beeware.org). However, I'm not sure if the language switcher can be configured to use a domain-based URL pattern.
2. Use Github Pages for hosting. Use RTD for PR previews, but remove most of the language variants. Add a CI task to run docs-lint and docs-all to confirm that the builds will complete, add a "publish" CI task also does a full build, then copies the _build/html/en/* folder to _build/html, and then publishes _build/html to a gh-pages branch as the GitHub pages site. This would also require renaming this repo to beeware.github.io, as that is a requirement for Github; the existing repo with that name would need to renamed first.

[freakboy3742]

Option (2) has the additional advantages that:

1. it doesn't break beeware.org/mobile-wheels
2. It avoids the need for RTD advertising on our main site.

Working on the assumption that (2) is the likely option we'll pursue, I've set up a preliminary gh-pages branch as the start of this; https://beeware.org/website (i.e., this accounts CNAME based on the beeware.github.io repo, using this repo's name as a path) is currently serving the EN version of the site.