A package or a module's purpose is to contain a number of elements. A package contains modules as well as classes, global variables, and functions. A module contains classes, global variables, and functions. The top-level docstrings on these containers can act as roadmaps to explain the general features of the package or module. The details are delegated to the individual classes or functions.

We might have a module docstring that looks like the following code:

Blackjack Cards and Decks
=========================

This module contains a definition of :class:`Card`, 
:class:`Deck` and :class:`Shoe` suitable for Blackjack.

The :class:`Card` class hierarchy
---------------------------------

The :class:`Card` class hierarchy includes the following class definitions.

:class:`Card` is the superclass as well as being the class for number cards.
:class:`FaceCard` defines face cards: J, Q and K.
:class:`AceCard` defines the Ace. This is special in Blackjack because it creates a soft total for a hand.

We create cards using the :func:`card` factory function to create the proper
:class:`Card` subclass instances from a rank and suit.

The :class:`Suit` enumeration has all of the Suit instances.

::

    >>> from ch20_ex1 import cards
    >>> ace_clubs= cards.card( 1, cards.suits[0] )
    >>> ace_clubs
    'A♣'
    >>> ace_diamonds= cards.card( 1, cards.suits[1] )
    >>> ace_clubs.rank ==  ace_diamonds.rank
    True

The :class:`Deck` and :class:`Shoe` class hierarchy
---------------------------------------------------

The basic :class:`Deck` creates a single 52-card deck. 
The :class:`Shoe` subclass creates a given number of decks. 
A :class:`Deck` can be shuffled before the cards can be 
extracted with the :meth:`pop` method. 
A :class:`Shoe` must be shuffled and
*burned*. The burn operation sequesters a random number of cards 
based on a mean and standard deviation. The mean is a number of 
cards (52 is the default.) 
The standard deviation for the burn is 
also given as a number of cards (2 is the default.)

Most of the text in this docstring provides a roadmap to the contents of this module. It describes the class hierarchies, making it slightly easier to locate a relevant class. References to classes use RST inline markup. There is a role prefix followed by the reference; for example, :class:`Card` generates text that will be a hyperlink to the definition of the Card class. We'll look at these references later. In a purely Python environment, these simple references work nicely; in a polyglot environment, or when using Sphinx outside Python, there are some important variations on the role names.

The docstring includes a simple example of the card() factory function based on doctest. This advertises this function as an important feature of the module as a whole. It might make sense to provide the doctest explanation of the Shoe class, as that's perhaps the most important part of this module.

This docstring includes some inline RST markup to put class names into a monospaced font. The section titles are underlined with === and --- lines. The RST parser can determine that the heading underlined with === is the parent of the headings underlined with ---.

We'll look at using Sphinx to produce the documentation in a later section. Sphinx will leverage the RST markup to produce great-looking HTML documentation.

Now, let's look at how to write API details in RST markup.