more documentation work

Author: bckohan

.gitignore

@@ -135,3 +135,5 @@ tests/edit_tests/migrations/00*.py
 benchmark.db
 type_check.py
 tests/**/migrations/**py
+
+.DS_Store

doc/source/eccentric_enums.rst

@@ -1,6 +1,6 @@
 .. include:: refs.rst
 
-.. _eccentric_enums:
+.. _eccentric:
 
 ======================
 Eccentric Enumerations
@@ -52,8 +52,8 @@ Mixed value enumerations are supported. For example:
         VAL4 = Decimal('4.5')
 
 
-``EnumField`` will determine the most appropriate database column type to store
-the enumeration by trying each of the supported primitive types in order and
+:class:`~django_enum.fields.EnumField` will determine the most appropriate database column type
+to store the enumeration by trying each of the supported primitive types in order and
 selecting the first one that is symmetrically coercible to and from each
 enumeration value. ``None`` values are allowed and do not take part in the
 primitive type selection. In the above example, the database column type would
@@ -62,12 +62,12 @@ be a string.
 .. note::
 
     If none of the supported primitive types are symmetrically coercible
-    ``EnumField`` will not be able to determine an appropriate column type and
-    a ``ValueError`` will be raised.
+    :class:`~django_enum.fields.EnumField` will not be able to determine an appropriate column
+    type and a ``ValueError`` will be raised.
 
 In these cases, or to override the primitive type selection made by
-``EnumField``, pass the ``primitive`` parameter. It may be necessary to extend
-one of the supported primitives to make it coercible. It may also be necessary
+:class:`~django_enum.fields.EnumField`, pass the ``primitive`` parameter. It may be necessary to
+extend one of the supported primitives to make it coercible. It may also be necessary
 to override the Enum_'s ``_missing_`` method:
 
 .. code-block:: python
@@ -78,8 +78,8 @@ to override the Enum_'s ``_missing_`` method:
     # primitive will be a float
     eccentric_float = EnumField(EccentricEnum, primitive=float)
 
-In the above case since ``None`` is an enumeration value, ``EnumField`` will
-automatically set null=True on the model field.
+In the above case since ``None`` is an enumeration value, :class:`~django_enum.fields.EnumField`
+will automatically set null=True on the model field.
 
 Custom Enumeration Values
 =========================

doc/source/flag_enums.rst

@@ -77,11 +77,11 @@ to:
 * Enforce enumeration value consistency at the database level using check constraints by default.
 * (TODO) Support native database enumeration column types when available.
 
-django-enum_ provides a new model field type, ``EnumField``, that allows you to treat almost any
-PEP 435 enumeration as a database column. ``EnumField`` resolves the correct native Django_ field
-type for the given enumeration based on its value type and range. For example, ``IntegerChoices``
-that contain values between 0 and 32767 become
-`PositiveSmallIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield>`_.
+django-enum_ provides a new model field type, :class:`~django_enum.fields.EnumField`, that allows
+you to treat almost any PEP 435 enumeration as a database column.
+:class:`~django_enum.fields.EnumField` resolves the correct native Django_ field type for the given
+enumeration based on its value type and range. For example, ``IntegerChoices`` that contain values
+between 0 and 32767 become `PositiveSmallIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield>`_.
 
 .. code-block:: python
 
@@ -111,8 +111,8 @@ that contain values between 0 and 32767 become
         int_enum = EnumField(IntEnum, default=IntEnum.ONE)
 
 
-``EnumField`` **is more than just an alias. The fields are now assignable and accessible as their
-enumeration type rather than by-value:**
+:class:`~django_enum.fields.EnumField` **is more than just an alias. The fields are now assignable
+and accessible as their enumeration type rather than by-value:**
 
 .. code-block:: python
 
@@ -157,6 +157,9 @@ reduction both speeds up queries and reduces the required storage space. See the
     # get all models with RW:
     FlagExample.objects.filter(permissions__has_all=Permissions.READ | Permissions.WRITE)
 
+.. note::
+
+    The :ref:`has_all` and :ref:`has_any` field lookups are only available for Flag enumerations.
 
 Complex Enumerations
 ====================
@@ -307,7 +310,6 @@ Please report bugs and discuss features on the
    :caption: Contents:
 
    usage
-   flag_enums
    examples
    performance
    eccentric_enums

doc/source/index.rst

@@ -24,7 +24,7 @@ or eccentric enumeration cases.
 
     The marshalling penalty can be eliminated by setting ``coerce`` to
     ``False``. This will require the developer to manually coerce the
-    ``EnumField`` value to an Enum_ type object and is therefore usually
+    :class:`~django_enum.fields.EnumField` value to an Enum_ type object and is therefore usually
     not recommended - but may be appropriate if the dominate use case involves
     high volume serialization to a raw value instead.
 
@@ -40,7 +40,7 @@ There is an obvious storage improvement when using a single column bit mask inst
 we achieve better query performance as well? The following benchmarks compare storage and query
 performance between boolean columns and bit masks.
 
-**Using a flag** ``EnumField`` **out performs boolean columns in both
+**Using a flag** :class:`~django_enum.fields.EnumField` **out performs boolean columns in both
 storage and query performance in most scenarios.**
 
 .. note::
@@ -57,7 +57,7 @@ storage and query performance in most scenarios.**
 No Indexing
 -----------
 
-When no indexes are used, the flag ``EnumField`` saves a significant amount
+When no indexes are used, the flag :class:`~django_enum.fields.EnumField` saves a significant amount
 of space over the boolean column model. The following plot shows the storage
 efficiency improvement over boolean columns as the number of flags increases
 for each supported RDBMS. The oracle line shows extents which are allocated in
@@ -94,13 +94,14 @@ does a full table scan:
 Indexed Exact Queries
 ---------------------
 
-When an index is used, the flag ``EnumField`` marginally outperforms the
+When an index is used, the flag :class:`~django_enum.fields.EnumField` marginally outperforms the
 boolean column equivalent in both storage and query performance for exact match
 queries. It is also much simpler to define. When using the boolean column
 approach a multi-column index must be used. By default PostgreSQL is compiled
 with a maximum multi-column index size of 32 columns. This means that masks
 with more than 32 flags must be split into multiple multi-column indexes which
-will further degrade performance compared to the equivalent flag ``EnumField``.
+will further degrade performance compared to the equivalent flag
+:class:`~django_enum.fields.EnumField`.
 
 The multi-column limit on MySQL is only 16 columns.