diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile | 20 | ||||
-rw-r--r-- | docs/_static/blinker-named.png | bin | 0 -> 3627 bytes | |||
-rw-r--r-- | docs/conf.py | 33 | ||||
-rw-r--r-- | docs/index.rst (renamed from docs/source/index.rst) | 31 | ||||
-rw-r--r-- | docs/make.bat | 35 | ||||
-rw-r--r-- | docs/source/Makefile | 54 | ||||
-rw-r--r-- | docs/source/conf.py | 146 |
7 files changed, 106 insertions, 213 deletions
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 Binary files differnew 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 |