Clarify and improve documentation. (#43)

Author: domdfcoding

doc-source/_static/style.css

@@ -0,0 +1,3 @@
+p {
+    margin-bottom: 12px;
+}

doc-source/api/autoenum.rst

@@ -1,6 +1,138 @@
-===================================
-:mod:`enum_tools.autoenum`
-===================================
+================================================
+:mod:`enum_tools.autoenum` -- Sphinx Extension
+================================================
+
+A Sphinx directive for documenting :class:`Enums <enum.Enum>` in Python.
+
+Provides the :rst:dir:`autoenum` directive for documenting :class:`Enums <enum.Enum>`,
+and :rst:dir:`autoflag` for documenting :class:`Flags <enum.Flag>`.
+These behaves much like :rst:dir:`autoclass` and :rst:dir:`autofunction`.
+
+.. extras-require:: sphinx
+	:pyproject:
+	:scope: extension / module
+
+.. extensions:: enum_tools.autoenum
+
+.. contents:: Sections
+	:depth: 1
+	:local:
+	:backlinks: none
+
+
+Usage
+---------
+
+.. rst:directive:: autoenum
+				   autoflag
+
+	These directives are used for documenting :class:`Enums <enum.Enum>` and :class:`Flags <enum.Flag>` respectively.
+
+	They support the same options as :rst:dir:`autoclass`, but with a few changes to the behaviour:
+
+	* Enum members are always shown regardless of whether they are documented or not.
+	* Enum members are grouped separately from methods.
+
+	The docstrings of the Enum members are taken from their ``__doc__`` attributes.
+	This can be set during initialisation of the enum (see an example `here <https://stackoverflow.com/a/50473952>`_),
+	with the :class:`~enum_tools.documentation.DocumentedEnum` class, or with the :func:`~enum_tools.documentation.document_enum` decorator.
+
+	See the `autodoc module documentation`_ for further details
+	of the general :rst:dir:`autoclass` behaviour.
+
+	.. _autodoc module documentation: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+
+.. rst:role:: py:enum:mem
+              py:enum:member
+              py:flag:mem
+              py:flag:member
+
+	These roles provide cross-references to Enum/Flag members.
+
+	.. versionadded:: 0.4.0
+
+	Unlike a standard ``:class:`` or ``:enum:`` xref the default behaviour of the
+	``~`` prefix is to show both the Enum's name and the member's name.
+	For example:
+
+	.. rest-example::
+
+		:py:enum:mem:`~enum_tools.demo.StatusFlags.Running`
+
+	The original behaviour can be restored by using the ``+`` prefix:
+
+	.. rest-example::
+
+		:py:enum:mem:`+enum_tools.demo.StatusFlags.Running`
+
+
+.. latex:vspace:: 10px
+
+Demo
+----------
+
+**These two have been created with** ``automodule``.
+
+.. container:: rest-example
+
+	.. code-block:: rest
+
+		.. automodule:: enum_tools.demo
+			:members:
+
+	.. automodule:: enum_tools.demo
+		:members:
+		:exclude-members: NoMemberDoc,StatusFlags,People
+		:noindex:
+		:no-autosummary:
+
+	.. latex:clearpage::
+
+	.. automodule:: enum_tools.demo
+		:members:
+		:exclude-members: NoMemberDoc,StatusFlags,NoMethods
+		:noindex:
+		:no-autosummary:
+
+.. raw:: html
+
+	<p></p>
+
+
+.. latex:vspace:: 10px
+
+**This one has been created with** ``autoenum``.
+
+.. rest-example::
+
+	.. autoenum:: enum_tools.demo.People
+		:members:
+
+
+.. latex:clearpage::
+
+**If members don't have their own docstrings no docstring is shown:**
+
+.. rest-example::
+
+	.. autoenum:: enum_tools.demo.NoMemberDoc
+		:members:
+
+
+.. latex:vspace:: 10px
+
+**Flags can also be documented:**
+
+.. rest-example::
+
+	.. autoflag:: enum_tools.demo.StatusFlags
+		:members:
+
+
+API Reference
+---------------
 
 .. automodule:: enum_tools.autoenum
+	:no-docstring:
 	:exclude-members: innernodeclass

doc-source/api/custom_enums.rst

@@ -2,4 +2,5 @@
 :mod:`enum_tools.custom_enums`
 ===================================
 
+.. autosummary-widths:: 30/100
 .. automodule:: enum_tools.custom_enums

doc-source/api/documentation.rst

@@ -2,6 +2,8 @@
 :mod:`enum_tools.documentation`
 ===================================
 
+.. module:: enum_tools.documentation
+.. autosummary-widths:: 35/100
 
 Core Functionality
 --------------------
@@ -18,13 +20,13 @@ Core Functionality
 .. autofunction:: enum_tools.documentation.document_member
 
 
-
+.. latex:clearpage::
 
 Utilities
 --------------------
 
 .. automodulesumm:: enum_tools.documentation
-	:exclude-members: DocumentedEnum,document_enum,document_member
+	:autosummary-exclude-members: DocumentedEnum,document_enum,document_member
 
 .. autofunction:: enum_tools.documentation.get_base_indent
 

doc-source/api/utils.rst

@@ -2,4 +2,5 @@
 :mod:`enum_tools.utils`
 =========================
 
+.. autosummary-widths:: 35/100
 .. automodule:: enum_tools.utils

doc-source/autoenum.rst

@@ -73,3 +73,21 @@ def setup(app):
 
 
 html_logo = "../enum_tools.png"
+autosummary_widths_builders = ["latex"]
+nitpicky = True
+needspace_amount = "1\\baselineskip"
+ignore_missing_xrefs = [
+		"^sphinx.ext.autodoc.(Class|Attribute)?Documenter$",
+		"^enum.EnumMeta$",
+		"^docutils.nodes.Element$",
+		"^sphinx.domains"
+		]
+# stdlib
+from typing import Type
+
+# 3rd party
+import enum_tools.autoenum
+from sphinx.ext.autodoc.directive import DocumenterBridge
+
+enum_tools.autoenum.DocumenterBridge = DocumenterBridge
+enum_tools.autoenum.Type = Type

doc-source/conf.py

@@ -1,5 +1,6 @@
-Overview
----------
+==============
+Contributing
+==============
 
 .. This file based on https://github.com/PyGithub/PyGithub/blob/master/CONTRIBUTING.md
 

doc-source/contributing.rst

@@ -134,13 +134,19 @@ Enum Tools
 .. end shields
 
 
-This library provides the following:
+Overview
+------------
+
+.. latex-section::
 
-#. A decorator to add docstrings to ``Enum`` members from a comment at the end of the line.
 
-#. A ``Sphinx`` extension to document Enums better than :rst:dir:`autoclass` can currently.
+This library provides the following:
 
-#. Additional ``Enum`` classes with different functionality.
+#. :mod:`enum_tools.autoenum` -- A `Sphinx <https://www.sphinx-doc.org>`_ extension to document Enums better than :rst:dir:`autoclass`
+   can currently.
+#. :deco:`enum_tools.documentation.document_enum` -- A decorator to add docstrings to :class:`~enum.Enum` members
+   from a comment at the end of the line.
+#. :mod:`enum_tools.custom_enums` -- Additional :class:`~enum.Enum` classes with different functionality.
 
 
 Installation
@@ -156,30 +162,34 @@ Installation
 
 .. end installation
 
-.. toctree::
-	:hidden:
 
-	Home<self>
+Contents
+------------
+
+.. html-section::
+
 
 .. toctree::
-	:maxdepth: 3
-	:caption: Documentation
+	:hidden:
 
-	autoenum
+	Home<self>
 
 .. toctree::
 	:maxdepth: 3
-	:caption: API Reference
 	:glob:
 
 	api/*
 
-.. toctree::
-	:maxdepth: 3
-	:caption: Contributing
 
-	contributing
-	Source
+.. only:: html
+
+	.. toctree::
+		:maxdepth: 3
+		:glob:
+
+		contributing
+		Source
+		license
 
 .. sidebar-links::
 	:caption: Links
@@ -195,16 +205,17 @@ Installation
 
 	:github:repo:`Browse the GitHub Repository <domdfcoding/enum_tools>`
 
-.. end links
 
 
 Further Reading
 -----------------------
 
-#. https://docs.python.org/3/library/enum.html
+.. html-section::
 
-#. `Is it possible to define a class constant inside an Enum? <https://stackoverflow.com/q/17911188/3092681>`_
 
-#. `Enums with Attributes <https://stackoverflow.com/a/19300424/3092681>`_
+.. only:: html
 
-#. `When should I subclass EnumMeta instead of Enum? <https://stackoverflow.com/a/43730306/3092681>`_
+	* https://docs.python.org/3/library/enum.html
+	* `Is it possible to define a class constant inside an Enum? <https://stackoverflow.com/q/17911188/3092681>`_
+	* `Enums with Attributes <https://stackoverflow.com/a/19300424/3092681>`_
+	* `When should I subclass EnumMeta instead of Enum? <https://stackoverflow.com/a/43730306/3092681>`_

doc-source/index.rst

@@ -1,3 +1,4 @@
+git+https://github.com/sphinx-toolbox/sphinx-toolbox-experimental
 default-values>=0.5.0
 domdf-sphinx-theme>=0.3.0
 extras-require>=0.2.0