FEDIDEVS

Hey! Are you at #PyConUS and interested in #CivicTech? Come join me and @civicband and chat about how you can help where you live with #python

3pm in room 201b

A brief note about the future of MkDocs:

- MkDocs 1.0 not maintained
- MkDocs 2.0: not backwards compatible
- ProperDocs: fork to preserve 1.0
- Zensical: drop in replacement
- General migration process is the same

#PyConUS

Beginning to end, the project took over nine months (ed: docs are babby?)

It took hours upon hours of work and reviews.

Would @beeware do it again?

Absolutely yes.

Should you do it? Only you can decide, but there is a path to success.

#PyConUS

This project was not a purely technical set of changes! It required a significant human element, including:

- Presenting a successful proposal
- Deliverable, not just doable progress
- Staged changes and incremental completion
- Engaging the community

#PyConUS

The @beeware website took three months. It really stretched the capabilities of the tooling, but once done it meant BeeWare has one unified set of tooling for all docs.

#PyConUS

First major docs site to be converted: the #BeeWare tutorial.

This took two weeks!

For reference, the toga docs took two and a half _months_ to convert.

Manual verification was critical. There was a full side-by-side comparison and verification between old and new.

Briefcase took three days. Simpler surface area and tooling improvements helped tremendously.

#PyConUS

Linting and checking on the generated Markdown was also critical. The pipeline checks for spelling, link validity, and more.

BeeWare now also has a comprehensive suite of docs tools, including sandboxing, single source for deps, unified theme, and shared common content.

Now, with the migration prepared, the real migration could start!

#PyConUS

Pandoc itself needed work to help the conversion

- Pandoc Markdown extensions
- CommonMarkX
- custom Pandoc scripts for finding and converting content

DocStrings had to be converted with regex (😱)

(ed: I will not be scribing the regex, I value my sanity)

#PyConUS

What MkDocs plugins did help?

- attr_list
- mkdocs-autorefs
- mkdocs-macros
- mkdocs-literate-nav
- mkdocstrings
- PyMDown extensions

PyMDown gets _special_ shoutout for all the features it provides out of the box.

#PyConUS

Early win: MkDocs live preview is quicker than Sphinx! This sped up development time.

Once basic viability was established, translation support was needed.

There isn't a built-in translation system for MkDocs, or the maturity of plugins that Sphinx has.

Creating and running build scripts for #BeeWare was necessary.

#PyConUS