FEDIDEVS

The fire under my behind to get a Trusted Publishing setup for something not GitHub/gitlab based continues to grow.

We must remove every barrier to getting off github.

#PyConUS

@kattni is a Core Developer on @beeware, as well as being the Chair of @pyohio

She led the documentation migration project for #BeeWare

#PyConUS

The @ThePSF should put on Python.org that you can get #python for “$9.99 (just kidding)” and see if donations go up 😂

#PyConUS

Hello #PyConUS! It's time for @kattni's talk: "Switching from Sphinx to Markdown"

Come join us in Ballroom B

Starting by ack'ing that there's a shift in the MkDocs community right now; everything Kattni will be talking about will remain applicable.

Now: What is rst?
#PyConUS

rst and sphinx have been used in #Python for 20 years! It has a ton of community support, and BeeWare's docs were originally in rst using Sphinx

So what about markdown?

#PyConUs

Markdown has been around for over a decade, and has wide support and adoption across platforms and ecosystems.

It's well-known as a format, and is now a viable alternative for rich tech docs

#PyConUS

Markdown's biggest issue tends to be the disagreements around what the "standard" flavor of Markdown is. Gruber has refused to release a standard, creating a wide collection of competing flavors.

That said, there's still a rough consensus.

#PyConUS

Now for the #BeeWare migration.

@beeware is a suite of tools to let you write cross-platform GUI applications entirely in python.

@kattni started by tackling documentation isses, and @freakboy3742 lamented the current state of reST.

Kattni saw an opportunity for improvement.

#PyConUS

One challenge is #BeeWare has the website, the tutorials, and docs collections for every repo and project.

The website was originally using Lektor in reST mode. It was... rough.

Kattni started by using Pandoc and the Lektor API to start the migration.

Full conversion was not the original goal, proving it was possible was the goal.

#PyConUS