Guide

These pages cover the one task docshare exists for — sharing documentation between related objects — in the order you are likely to meet it. Start with Inheriting for the many ways to say what to inherit; the pages that follow take up the two formats, sections of your own, signature checking, reading and composing documentation without decorating anything, threads, and errors. Concepts and design steps back to the design and the invariants behind all of it, and is worth reading when a rule seems surprising.

• Inheriting
  • Several sources
  • One item from one source
  • A source whose format must be stated
  • Skipping
  • Renaming
  • Parameters your signature does not show
  • Returns, raises, and the rest
  • Everything at once
  • The summary and the description
  • Sections docshare has never heard of
  • The general form
  • Composition happens once
• Sections
  • What each section offers
  • Grouped declarations
  • Prose that introduces a section
  • Sections docshare does not recognize
• Formats
  • format and render
  • Items with no type
  • One ambiguity worth knowing about
  • Prose that ends in a colon
  • Keyword arguments
  • What rendering preserves
• Custom sections
  • Declaring a section
  • Declaring a section without a kind
  • Nothing is registered
  • Inheriting a declared section
  • Titles that are not Python names
  • Sources: sourcecustom and sourceformat
  • The three format arguments
  • What a declaration cannot do
• Signatures
  • The rule
  • **kwargs does not excuse anything
  • What is checked
  • Objects without signatures
  • Objects that can be decorated
• Reading documentation
  • The document model
  • The cache
• Without decorating
  • The composed document
  • What you can give them
  • Rendering is a rewrite
• Threads
  • Why a lock is needed at all
  • Parsing happens outside the lock
  • What is not guaranteed
• Errors
  • When errors are raised
• Concepts and design
  • Where docshare sits
  • Goals
  • Non-goals
  • The core invariants
  • Dependencies