Skip to content

Instantly share code, notes, and snippets.

@qwcode
Last active July 5, 2023 08:55
Show Gist options
  • Save qwcode/8431828 to your computer and use it in GitHub Desktop.
Save qwcode/8431828 to your computer and use it in GitHub Desktop.
"Pypa Standard Docs Template"

A basic structure for Pypa project docs

why a consistent structure? in large part for making the "Python Packaging User Guide" more effective when linking and less redundant

All the projects should use the default RTD theme to match the User Guide.

Introduction

thinking this doesn't have be a top-level section, but rather just a paragraph or two at the top of the index page. should include the following links: User list | Dev list | Issues | Github | PyPI | irc (e.g. see http://www.pip-installer.org/en/latest/)

Installation

should be a top-level section, even if it's short.

Quickstart

super quick command sequences to get going. e.g. for pip, covers the basic 4 or 5 pip commands people use.

User Guide

not a reference, but a topical guide that covers the common situations and commands people need.

Reference Guide

ideally, this is automated through introspection of command classes, and option objects. (e.g. pip's "usage" section is currently automated)

  • e.g. for pip, should cover all subcommands and options.
  • e.g. for wheel's bdist_wheel, it should cover all the options
  • e.g. for setuptools, should cover all setup.py commands and options (including pure-distutils)

Development

  • how to test
  • release procedures
  • how to get involved
  • irc channels...

Release History

  • the changelog
  • don't use sections to mark releases, because it makes the TOC too noisy
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment