Posit just announced the release of their new Quarto-based Python package documentation site generator: great-docs.
This is part 1 of a now much saner three-part series.
Part 2 is the conceptual notebook-driven development post. Part 3 will be the concrete implementation and tutorial.
In a nutshell, great-docs is a Python package documentation site generator that:
- inspects your package and auto-generates API reference pages
- identifies and documents Click-based CLIs
- automatically turns your
README.mdinto a landing page - renders narrative docs from a
user_guide/directory - supports extra sections for tutorials, recipes, blog posts, and similar content
- builds a beautiful site with Quarto
The Quarto folks have ensured that the workflow path is ridiculously compact. Given a Python package, you can get a documentation site up and running in three commands:
pip install great-docs
great-docs init
great-docs build
great-docs preview
The docs note two important practical constraints up front: first, it requires Python >=3.111, and Quarto is the rendering engine doing the heavy lifting under the hood.
This is particularly important. In the R world, we’ve been blessed for many years with pkgdown, and I’ll be honest: it is one of my top reasons to start a multilingual project in R instead of Python. With pkgdown, you use Roxygen tags to annotate your functions, and from there most of the annoying package documentation work becomes much more civilized. Today, pkgdown sites are ubiquitous and instantly identifiable, and in my opinion they are a strong indicator of code quality and attention to detail.
Python, of course, has had documentation tooling for a long time too. The first time I documented a Python package, I used Sphinx, and it was…alright. It was certainly more work than I wanted, and it felt like I had to stop developing to go become a documentation engineer for a while. Since then, Python has accumulated multiple docstring conventions and documentation workflows, including Google Style, NumPy style, and Sphinx-style docstrings. One of my long-running gripes with Python is that because it is so easy to publish new things, the ecosystem can quickly become a bit of an “anything goes” frontier, and the documentation space is no different.
Each time somebody tries to establish the one true standard, we end up back in the old “conflicting standards” comic:
Now we have great-docs. So why do I think this one might actually matter?
great-docs is NOT a Docstring Style Specification
This was the first thing I wanted to verify in the docs, because if Posit had tried to invent yet another docstring religion, I would have been far less excited.
Thankfully, that is not what is happening here.
great-docs is a Quarto-driven documentation generator, not a new docstring style. According to the docs and repo, it detects and works with NumPy, Google, and Sphinx-style docstrings. Instead of asking the Python community to start yet another standards war, it just accepts the reality that the war already happened, and tries to produce one clean output from the mess.
Instantly, I’m more than a little interested.
great-docs is Driven By Quarto
Quarto is clearly picking up speed in the data science community, and I care a lot about tools that meet scientists and research programmers where they already work.
The easier it is to integrate Quarto into existing software development infrastructure, the more confidence I have that a tool will actually stick. Quarto already gives us documents, websites, blogs, books, notebooks, and an extension system that is much more fun than it has any right to be.2
If great-docs had shown up with its own peculiar rendering stack, I would have been skeptical. But showing up as, “use Quarto, but use it for package docs too,” just makes sense.
Pseudo-Corporate Backing
Hear me out.
As an academic and a FOSS-minded person, I am usually wary any time a company starts drifting toward “this should be the standard.” But in this case, we’re talking about Posit, a not-for-profit PBC that has already earned over a decade of trust from people who do data for a living. Quarto is one of their flagship projects, and great-docs feels like a natural extension of that ecosystem rather than an opportunistic side quest.
If you have already trusted Posit with Quarto, I don’t think it’ll be a stretch to trust them taking a serious swing at package documentation too.
Multilinguists Will Now Have An Easy On-Ramp
There are a lot of R users who still feel a bit skittish about Python. Part of that is cultural. R tends to feel a little more analyst-native, while Python often feels like you are stepping into the software engineers’ world whether you meant to or not.
Posit has spent years positioning itself as a polyglot data science company first and foremost,3 and I think that matters. If great-docs gives R users a familiar on-ramp into Python package documentation, that is a win in my book. Likewise, if it nudges Python users into the broader Quarto ecosystem, where they might bump into R users, that is even better. I like tools that lower the social cost of crossing language boundaries and erode social inertia.
Verdict
I am obviously biased here. I like what Posit builds, and I especially like what Quarto makes possible. That said, I am not completely uncritical. I still have not fully moved into Positron as an IDE, mostly because my life involves remote HPC systems, and those environments are great at humbling product claims.
Still: most of what Posit ships is pretty thoughtful, and a lot of it is damn near excellent. After reading through the great-docs docs rather than just freestyling from the announcement, I think this is a genuinely promising release.
More importantly, I think it opens the door to something I care about more than documentation alone: a Quarto-native, notebook-driven development workflow for Python packages that does not feel bolted on after-the-fact.
That’s where I am headed next.
Part 2 is the conceptual case for that workflow. Part 3 is where I will get into the actual implementation details.
See you then!
Footnotes
So go ahead and install πthon, lol.↩︎
The extension ecosystem is already getting interesting. The
awesome-quartorepo is a good place to poke around.↩︎Wes McKinney’s JupyterCon talk is still a good snapshot of Posit’s broader commitment to Python and multilingual data science.↩︎