Phil Ewels
Phil Ewels is Product Manager for Open Source at Seqera. He holds a PhD in Molecular Biology from the University of Cambridge, UK and has a career that has spanned many disciplines from scientific lab work and computational bioinformatics research in the life sciences, through to software development and community engagement. He is passionate about open-source software and has a soft spot for tools with a focus on user-friendliness. He is author of MultiQC, co-founder of the nf-core Nextflow bioinformatics community and creator of many small plugins and pet projects with varying degrees of popularity.
Session
Good documentation is really important for the success of a Python package. Good docs open the door for discovery, installation and usage. Great docs have guides, examples, and a complete reference for the Python API surface.
Python docstrings are the perfect place to write the reference docs. They sit next to the code that's being written, staying updated and helping contributors. No-one wants to write the same thing twice, so the reference docs should be generated from the Python source directly.
Astro Starlight is a modern, fast, and static site generator for documentation websites that is rapidly gaining popularity. It handles the hand-written half beautifully, with lots of functionality and components available out the box. It also has a strong community of theme and plugin authors. I wrote starlight-pydocs to make it super easy to build Starlight documentation websites for your Python package. It's the perfect package for anyone moving away from mkdocs and mkdocstrings.
All that Starlight Pydocs needs is a couple of lines of configuration, and you get an automatically built API docs section with one page per module. Docs show signatures with hyperlinked types, parameter tables, inherited members with provenance and full syntax highlighting. The plugin is agent-friendly: every page also answers as plain Markdown, and each package publishes an llms.txt and a Sphinx inventory so other sites can link to yours.
In this talk I'll build a new docs site from scratch, live, and show how easy it is to get a beautiful docs site with Starlight.