![[py.wtf/Preamble]] Producing documentation for Python code sucks. Especially for a relative newcomer to the space, having to do all of: - learn restructured text - pick some documentation framework (Sphinx, pydoc, etc) based on their tradeoffs - learn and (re)write the documentation in the chosen framework's markup - pick a hosting provider based on _their_ tradeoffs - configure the hosting provider - set up CI to compile your documentation and publish to the hosting provider Just reading through that list makes me despair and not even want to try. Why can't we have a zero-cost way of producing good-enough quality documentation for your average python projects? We already have docstrings and type annotations. We should be able to produce pretty good docs with just these two, if [docs.rs](https://docs.rs) and [hackage](https://hackage.haskell.org/) is any indication. This is what motivated [the three of us](https://github.com/zsol/py.wtf#acknowledgements) to start the py.wtf project. ## Principles - Absolutely no configuration necessary for published pypi projects: be opinionated enough to cover the vast majority of doc needs - Meet the developer where they are: use docstrings, type annotations, and whatever markup they use - Minimal maintenance costs: both in terms of hosting costs and human attention necessary - Easy and fast to use ## High quality documentation Really excellent documentation like the official Python docs, https://trio.readthedocs.io/en/stable/, https://www.attrs.org/en/stable/, and others will always require a lot of effort and customization. This project doesn't aim to replace these; instead, if py.wtf is successful there should be a noticeably smaller gap between the above examples and your average Python project's documentation. The hope is to raise the tide: if writing docs is no more effort than plain-text docstrings and type hints, maybe fewer people will shrug and skip it after concluding it's way too much effort anyway. ## Next up - [[Web Architecture|Web Architecture]] - Indexing - Kinds of documentation we extract - Future ideas