update sphinx config

9 files changed, 108 insertions, 229 deletions

diff --git a/.gitignore b/.gitignore
index 52b37ea..3c90d3f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,11 +5,4 @@
 build
 dist
 MANIFEST
-docs/text
-docs/html
-docs/doctrees
-docs/doctest
-docs/pickles
-docs/source/_static
-docs/source/_template
-docs/website
+docs/_build
diff --git a/blinker/base.py b/blinker/base.py
index a44e893..8a3e4f9 100644
--- a/blinker/base.py
+++ b/blinker/base.py
@@ -195,14 +195,7 @@ class Signal(object):
         the duration of the ``with`` block, and will be disconnected
         automatically when exiting the block:
 
-        .. testsetup::
-
-          from __future__ import with_statement
-          from blinker import Signal
-          on_ready = Signal()
-          receiver = lambda sender: None
-
-        .. testcode::
+        .. code-block:: python
 
           with on_ready.connected_to(receiver):
              # do stuff
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/blinker-named.png b/docs/_static/blinker-named.png
new file mode 100644
index 0000000..88e1818
--- /dev/null
+++ b/docs/_static/blinker-named.png
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..5bbd200
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,33 @@
+from pallets_sphinx_themes import get_version
+from pallets_sphinx_themes import ProjectLink
+
+project = "Blinker"
+copyright = "2010 Jason Kirtland"
+release, version = get_version("blinker", placeholder=None)
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "pallets_sphinx_themes",
+]
+
+autoclass_content = "both"
+autodoc_member_order = "groupwise"
+
+html_theme = "flask"
+html_theme_options = {"index_sidebar_logo": False}
+html_context = {
+    "project_links": [
+        ProjectLink("PyPI Releases", "https://pypi.org/project/blinker/"),
+        ProjectLink("Source Code", "https://github.com/pallets-eco/blinker/"),
+        ProjectLink("Issue Tracker", "https://github.com/pallets-eco/blinker/issues/"),
+    ]
+}
+html_sidebars = {
+    "index": ["project.html", "localtoc.html", "searchbox.html", "ethicalads.html"],
+    "**": ["localtoc.html", "relations.html", "searchbox.html", "ethicalads.html"],
+}
+singlehtml_sidebars = {"index": ["project.html", "localtoc.html", "ethicalads.html"]}
+html_static_path = ["_static"]
+html_logo = "_static/blinker-named.png"
+html_title = f"Blinker Documentation ({version})"
+html_show_sourcelink = False
diff --git a/docs/source/index.rst b/docs/index.rst
index 5e8e470..82a41d5 100644
--- a/docs/source/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,11 @@
+.. rst-class:: hide-header
+
 Blinker Documentation
 =====================
 
+.. image:: _static/blinker-named.png
+    :align: center
+
 Blinker provides fast & simple object-to-object and broadcast
 signaling for Python objects.
 
@@ -25,7 +30,7 @@ Decoupling With Named Signals
 
 Named signals are created with :func:`signal`:
 
-.. doctest::
+.. code-block:: python
 
   >>> from blinker import signal
   >>> initialized = signal('initialized')
@@ -45,7 +50,7 @@ Subscribing to Signals
 the signal is emitted.  Connected functions are always passed the
 object that caused the signal to be emitted.
 
-.. doctest::
+.. code-block:: python
 
   >>> def subscriber(sender):
   ...     print("Got a signal sent by %r" % sender)
@@ -66,7 +71,7 @@ about to process something, and ``complete`` when it is done.  It
 passes ``self`` to the :meth:`~Signal.send` method, signifying that
 that particular instance was responsible for emitting the signal.
 
-.. doctest::
+.. code-block:: python
 
   >>> class Processor:
   ...    def __init__(self, name):
@@ -102,7 +107,7 @@ any sender emits it.  The :meth:`Signal.connect` function accepts an
 optional argument to restrict the subscription to one specific sending
 object:
 
-.. doctest::
+.. code-block:: python
 
   >>> def b_subscriber(sender):
   ...     print("Caught signal from processor_b.")
@@ -115,7 +120,7 @@ object:
 This function has been subscribed to ``ready`` but only when sent by
 ``processor_b``:
 
-.. doctest::
+.. code-block:: python
 
   >>> processor_a.go()
   Got a signal sent by <Processor a>
@@ -132,7 +137,7 @@ Sending and Receiving Data Through Signals
 Additional keyword arguments can be passed to :meth:`~Signal.send`.
 These will in turn be passed to the connected functions:
 
-.. doctest::
+.. code-block:: python
 
   >>> send_data = signal('send-data')
   >>> @send_data.connect
@@ -147,7 +152,7 @@ The return value of :meth:`~Signal.send` collects the return values of
 each connected function as a list of (``receiver function``, ``return
 value``) pairs:
 
-.. doctest::
+.. code-block:: python
 
   >>> result
   [(<function receive_data at 0x...>, 'received!')]
@@ -161,7 +166,7 @@ unique signal each time it is invoked.  For example, an alternative
 implementation of the Processor from above might provide the
 processing signals as class attributes:
 
-.. doctest::
+.. code-block:: python
 
   >>> from blinker import Signal
   >>> class AltProcessor:
@@ -187,7 +192,7 @@ You may have noticed the return value of :meth:`~Signal.connect` in
 the console output in the sections above.  This allows ``connect`` to
 be used as a decorator on functions:
 
-.. doctest::
+.. code-block:: python
 
   >>> apc = AltProcessor('c')
   >>> @apc.on_complete.connect
@@ -202,7 +207,7 @@ While convenient, this form unfortunately does not allow the
 ``sender`` or ``weak`` arguments to be customized for the connected
 function.  For this, :meth:`~Signal.connect_via` can be used:
 
-.. doctest::
+.. code-block:: python
 
   >>> dice_roll = signal('dice_roll')
   >>> @dice_roll.connect_via(1)
@@ -224,7 +229,7 @@ expensive to compute, it can be more efficient to check to see if any
 receivers are connected first by testing the :attr:`~Signal.receivers`
 property:
 
-.. doctest::
+.. code-block:: python
 
   >>> bool(signal('ready').receivers)
   True
@@ -236,7 +241,7 @@ property:
 Checking for a receiver listening for a particular sender is also
 possible:
 
-.. doctest::
+.. code-block:: python
 
   >>> signal('ready').has_receivers_for(processor_a)
   True
@@ -301,4 +306,4 @@ Named Signals
 Changes
 =======
 
-.. include:: ../../CHANGES.rst
+.. include:: ../CHANGES.rst
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..954237b
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/Makefile b/docs/source/Makefile
deleted file mode 100644
index 57b9bfe..0000000
--- a/docs/source/Makefile
+++ /dev/null
@@ -1,54 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-VERSION      ?= tip
-RELEASE      ?= $(VERSION)
-
-# Internal variables.
-ALLSPHINXOPTS   = -D version=$(VERSION) -D release=$(RELEASE) \
-   -d ../doctrees $(SPHINXOPTS) .
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  text      to make standalone text files"
-	@echo "  sdist     to build documentation for release"
-	@echo "  doctest   to run doctests"
-	@echo "  pickles   to build pickles"
-	@echo "  clean     to remove generated artifacts"
-
-sdist: clean text html
-
-clean:
-	for i in doctrees html text doctest pickles website; do \
-	    rm -rf ../$$i; \
-        done
-
-html:
-	mkdir -p ../html ../doctrees _static _template
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ../html
-	@echo
-	@echo "Build finished. The HTML pages are in ../html."
-
-text:
-	mkdir -p ../text ../doctrees
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) ../text
-	@echo
-	@echo "Build finished. The text pages are in ../text."
-
-doctest:
-	mkdir -p ../doctrees ../doctest
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) ../doctest
-
-pickles:
-	mkdir -p ../pickles ../doctest
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) ../pickles
-
-website:
-	mkdir -p ../website ../doctrees
-	$(SPHINXBUILD) -b discorporate \
-           -D html_theme=discorporate \
-           $(ALLSPHINXOPTS) ../website
diff --git a/docs/source/conf.py b/docs/source/conf.py
deleted file mode 100644
index ae1bcad..0000000
--- a/docs/source/conf.py
+++ /dev/null
@@ -1,146 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Blinker documentation build configuration file, created by
-# sphinx-quickstart on Mon Feb 15 10:54:13 2010.
-#
-# This file is execfile()d with the current directory set to its containing
-# dir.
-
-import os
-from os import path
-import sys
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-sys.path.append(os.path.abspath('../../'))
-sys.path.append(os.path.abspath('_themes'))
-
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.doctest',
-              'sphinx.ext.coverage']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'Blinker'
-copyright = u'2010, Jason Kirtland'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = 'tip'
-# The full version, including alpha/beta/rc tags.
-release = 'tip'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
-
-autoclass_content = "both"
-autodoc_member_order = "groupwise"
-import sphinx.ext.autodoc
-sphinx.ext.autodoc.AttributeDocumenter.member_order = 25
-sphinx.ext.autodoc.InstanceAttributeDocumenter.member_order = 26
-
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-html_static_path = ['_static']
-
-html_theme_path = ['_themes']
-
-html_theme = 'flask_small'
-
-html_theme_options = {
-    'index_logo':       'blinker-named.png',
-    'github_fork':      'jek/blinker'
-}
-
-html_title = 'Blinker'
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Blinkerdoc'
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'Blinker.tex', u'Blinker Documentation',
-   u'Jason Kirtland', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True