diff --git a/docs/reference/flags.rst b/docs/reference/flags.rst
new file mode 100644
index 00000000..d2bee822
--- /dev/null
+++ b/docs/reference/flags.rst
@@ -0,0 +1,21 @@
+=============
+Flags
+=============
+
+.. automodule:: ppb.flags
+
+--------------
+Base classes
+--------------
+
+This is the base class for defining new flags.
+
+.. autoclass:: ppb.flags.Flag
+
+----------------
+Metaclasses
+----------------
+
+The metaclass that makes the type hinting of flags possible.
+
+.. autoclass:: ppb.flags.FlagMeta
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 3d315865..8c8f306a 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -30,4 +30,5 @@ decisions are made, see the :doc:`/discussion/index` section.
    directions
    deprecations
    system
+   flags
    features/index
diff --git a/src/ppb/flags.py b/src/ppb/flags.py
index af48506a..ec86f4a7 100644
--- a/src/ppb/flags.py
+++ b/src/ppb/flags.py
@@ -1,17 +1,18 @@
 """
 ppb.flags contains singletons to communicate various things.
 
-Flags should be used like None and ... (Ellipsis):
-* compare against using `is`
+Flags should be used like ``None`` and ``...`` (Ellipsis):
+
+* compare against using ``is``
 * Do not instantiate new instances
 
-New flags can simply be defined by:
+New flags can simply be defined by::
 
     class MyFlag(Flag):
         "This is a flag to indicate a thing."
 
 
-New classes of flags (eg mouse buttons) can be defined as:
+New classes of flags (eg mouse buttons) can be defined as::
 
     class MyFlagType(Flag, abstract=True):
         "A group of indicators"