Why quartodocs
Context and problem statement
Documentation is one of the most important aspects of software, and an easy to access and navigate documentation makes the difference between it being used and not being used. We build websites for nearly all our documents, and we’d like to be able to also build a website of Python function docstrings, so there is an online reference that users can navigate to learn more about how to use the functions. So the question is:
Which docstring parser and converter should we use that fits our needs, values, and principles?
Decision drivers
Motivations for this decision:
- Navigating the function documentation is difficult since we have to go to the Python script to read it.
- Referencing Python functions within the existing website is not possible without an tool to do it for us, which means that information starts duplicating.
We also have some specific needs for how this documentation is generated:
- Parses Markdown, since our docstrings are written in Markdown
- Parses Google-style formatted docstrings (which we use)
- Converts to static HTML files or to plain Markdown files
- Incorporates into existing websites (that are built with Quarto)
- Allows control of what docstrings get generated, e.g. not generate internal functions
- Optionally, allows code-linking
- Optionally, allows theme and aesthetic customization
- Optionally, allows rendering diagram as code tools like Mermaid or PlantUML
Considered options
There are a wide variety of options for generating HTML files from Python docstrings. The ones that match our requirements as well as our values and philosophies are:
Below are other tools used within the Python community to generate documentation into websites, which we don’t consider because they don’t fit our requirements:
- MkDocs and Sphinx: These both are the most commonly used tools to generate HTML documentation. These are full static website generators that include a docstring-to-HTML converter. We already generate our websites with Quarto, so don’t need these.
- pydoc-markdown: This fits our requirements but it is not actively maintained.
mkdocstrings
Benefits
- Well supported and very actively maintained.
- Comes with cross-linking
Drawbacks
- Will need some configuration to integrate with our existing Quarto website.
- Doesn’t use CommonMark, which is the core spec underneath Quarto, so some Markdown syntax we use might not work and we will have to adjust based on that.
- Google style docstrings are still work in progress (as of writing this post).
- Requires filling in special syntax with YAML blocks for each function you want to insert into the Markdown file that will go on the website.
- Cross-linking seems to only work when generating the Markdown files through MkDocs.
- Most of the configurations must be put into a
mkdocs.ymlfile, which would not easily integrate with Quarto.
quartodoc
Benefits
- Since it is designed specifically with Quarto in mind, it comes with all the features that Quarto has, including Mermaid diagram generation, using our custom Quarto theme, and code-linking.
- Can wrap example code in the docstrings into executable code chunks that Quarto will render.
- Has unofficial backing from Quarto dev team, since it is developed (independently) by one of the Quarto dev team members.
Drawbacks
- More recently developed, so some features are still experimental.
- Not as actively developed and maintained, so any updates might take a while.
- Documentation is in various states of completion, so finding information might be tricky.
Decision outcome
While both choices are strong candidates, we ultimately chose quartodoc even though it is newer and less actively developed. There were too many drawbacks for the mkdocstrings for it to be a good fit for us.
Consequences
- Because it still is new, some features might be changed a lot, not work as intended, or have some bugs.
- We may have to be contributors to this project if we encounter any issues and work to fix it ourselves, which would take time away from developing Seedcase products.