diff --git a/.gitignore b/.gitignore
index a59d2bc5..8b50f464 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,12 +5,12 @@
*.sqlite
*.sqlite-journal
settings_local.py
-.build
-build
+build/
+.build/
+_build/
.*.sw[pon]
dist/
*.egg-info
-doc/__build/*
pip-log.txt
devdatabase.db
^parts
diff --git a/Changelog b/Changelog
index e84c0ae0..1ad73e4d 100644
--- a/Changelog
+++ b/Changelog
@@ -238,9 +238,9 @@
If you're using Django 1.8 and have already created the
kombu_transport_django tables, you have to run a fake initial migration:
- .. code-block:: pycon
+ .. code-block:: console
- python manage.py migrate kombu_transport_django --fake-initial
+ $ python manage.py migrate kombu_transport_django --fake-initial
- No longer compatible with South by default.
@@ -575,13 +575,17 @@
http://www.rabbitmq.com/blog/2014/04/02/breaking-things-with-rabbitmq-3-3/
A new connection property has been added that can be used to detect
- whether the remote server is using this new QoS behavior::
+ whether the remote server is using this new QoS behavior:
+
+ .. code-block:: pycon
>>> Connection('amqp://').qos_behavior_matches_spec
False
so if your application depends on the old semantics you can
- use this to set the ``apply_global`` flag appropriately::
+ use this to set the ``apply_global`` flag appropriately:
+
+ .. code-block:: python
def update_prefetch_count(channel, new_value):
channel.basic_qos(
@@ -668,7 +672,9 @@
messages.
This change is backwards incompatible and must be enabled with
- the ``fanout_patterns`` transport option::
+ the ``fanout_patterns`` transport option:
+
+ .. code-block:: pycon
>>> conn = kombu.Connection('redis://', transport_options={
... 'fanout_patterns': True,
@@ -871,7 +877,9 @@
- Redis: Unix socket URLs can now specify a virtual host by including
it as a query parameter.
- Example URL specifying a virtual host using database number 3::
+ Example URL specifying a virtual host using database number 3:
+
+ .. code-block:: text
redis+socket:///tmp/redis.sock?virtual_host=3
@@ -953,7 +961,9 @@
This transport option is recommended for all users as it ensures
that broadcast (fanout) messages sent is only seen by the current
- virtual host::
+ virtual host:
+
+ .. code-block:: python
Connection('redis://', transport_options={'fanout_keyprefix': True})
@@ -1023,11 +1033,15 @@
To have your consumer accept formats other than json you have to
explicitly add the wanted formats to a white-list of accepted
- content types::
+ content types:
+
+ .. code-block:: pycon
>>> c = Consumer(conn, accept=['json', 'pickle', 'msgpack'])
- or when using synchronous access::
+ or when using synchronous access:
+
+ .. code-block:: pycon
>>> msg = queue.get(accept=['json', 'pickle', 'msgpack'])
@@ -1326,7 +1340,9 @@ Changes
is raised. Note that this error can be handled by the already
existing `on_decode_error` callback
- Examples::
+ Examples:
+
+ .. code-block:: python
Consumer(accept=['application/json'])
Consumer(accept=['pickle', 'json'])
@@ -1390,7 +1406,9 @@ Changes
Ack emulation adds quite a lot of overhead to ensure data is safe
even in the event of an unclean shutdown. If data loss do not worry
you there is now an `ack_emulation` transport option you can use
- to disable it::
+ to disable it:
+
+ .. code-block:: python
Connection('redis://', transport_options={'ack_emulation': False})
@@ -1918,11 +1936,15 @@ SQS: Now supports long polling (Issue #176).
ensures that we can quickly roll out new features and fixes without
resorting to monkey patching.
- To use the py-amqp transport you must install the :mod:`amqp` library::
+ To use the py-amqp transport you must install the :mod:`amqp` library:
+
+ .. code-block:: console
$ pip install amqp
- and change the connection URL to use the correct transport::
+ and change the connection URL to use the correct transport:
+
+ .. code-block:: pycon
>>> conn = Connection('pyamqp://guest:guest@localhost//')
@@ -2081,16 +2103,18 @@ SQS: Now supports long polling (Issue #176).
- Exchange & Queue can now be bound to connections (which will use the default
channel):
- >>> exchange = Exchange('name')
- >>> bound_exchange = exchange(connection)
- >>> bound_exchange.declare()
+ .. code-block:: pycon
+
+ >>> exchange = Exchange('name')
+ >>> bound_exchange = exchange(connection)
+ >>> bound_exchange.declare()
- ``SimpleQueue`` & ``SimpleBuffer`` can now be bound to connections (which
will use the default channel).
- ``Connection.manager.get_bindings`` now works for librabbitmq and pika.
-- Adds new transport info attributes::
+- Adds new transport info attributes:
- ``Transport.driver_type``
@@ -2129,9 +2153,11 @@ Important Notes
these are named ``mailbox_name.pidbox``,
and ``reply.mailbox_name.pidbox``.
- The following command can be used to clean up these exchanges::
+ The following command can be used to clean up these exchanges:
- VHOST=/ URL=amqp:// python -c'import sys,kombu;[kombu.Connection(
+ .. code-block:: text
+
+ $ VHOST=/ URL=amqp:// python -c'import sys,kombu;[kombu.Connection(
sys.argv[-1]).channel().exchange_delete(x)
for x in sys.argv[1:-1]]' \
$(sudo rabbitmqctl -q list_exchanges -p "$VHOST" \
@@ -2146,7 +2172,9 @@ Important Notes
`py-librabbitmq`_ is a fast AMQP client for Python
using the librabbitmq C library.
- It can be installed by::
+ It can be installed by:
+
+ .. code-block:: console
$ pip install librabbitmq
@@ -2188,7 +2216,9 @@ News
this means that ETA/countdown tasks that are scheduled to execute
with a time that exceeds the visibility timeout will be executed
twice (or more). If you plan on using long ETA/countdowns you
- should tweak the visibility timeout accordingly::
+ should tweak the visibility timeout accordingly:
+
+ .. code-block:: python
BROKER_TRANSPORT_OPTIONS = {'visibility_timeout': 18000} # 5 hours
@@ -2218,7 +2248,9 @@ News
The priority range is collapsed into four steps by default, since it is
unlikely that nine steps will yield more benefit than using four steps.
The number of steps can be configured by setting the ``priority_steps``
- transport option, which must be a list of numbers in **sorted order**::
+ transport option, which must be a list of numbers in **sorted order**:
+
+ .. code-block:: pycon
>>> x = Connection('redis://', transport_options={
... 'priority_steps': [0, 2, 4, 6, 8, 9],
@@ -2414,7 +2446,9 @@ callback-based API later.
* SQLAlchemy: Can now specify url using + separator
- Example::
+ Example:
+
+ .. code-block:: python
Connection('sqla+mysql://localhost/db')
@@ -2533,7 +2567,9 @@ callback-based API later.
* Virtual transports: can now set polling interval via the
transport options (Issue #96).
- Example::
+ Example:
+
+ .. code-block:: pycon
>>> Connection('sqs://', transport_options={
... 'polling_interval': 5.0})
@@ -2587,7 +2623,9 @@ New Transports
is needed you shall consider switching to a non-polling transport.
To use it you must use transport alias ``"django"``,
- or as an URL::
+ or as an URL:
+
+ .. code-block:: text
django://
@@ -2598,10 +2636,14 @@ New Transports
If you have previously used ``django-kombu``, then the entry
in ``INSTALLED_APPS`` must be changed from ``djkombu``
- to ``kombu.transport.django``::
+ to ``kombu.transport.django``:
- INSTALLED_APPS = (…,
- 'kombu.transport.django')
+ .. code-block:: python
+
+ INSTALLED_APPS = (
+ # …,
+ 'kombu.transport.django',
+ )
If you have previously used django-kombu, then there is no need
to recreate the tables, as the old tables will be fully compatible
@@ -2625,7 +2667,9 @@ News
* SQS Transport: Added support for SQS queue prefixes (Issue #84).
The queue prefix can be set using the transport option
- ``queue_name_prefix``::
+ ``queue_name_prefix``:
+
+ .. code-block:: python
BrokerTransport('SQS://', transport_options={
'queue_name_prefix': 'myapp'})
@@ -2635,7 +2679,9 @@ News
* ``Producer.publish`` now supports automatic retry.
Retry is enabled by the ``reply`` argument, and retry options
- set by the ``retry_policy`` argument::
+ set by the ``retry_policy`` argument:
+
+ .. code-block:: python
exchange = Exchange('foo')
producer.publish(message, exchange=exchange, retry=True,
@@ -2699,7 +2745,9 @@ Fixes
than a feature.
If wanted the dead-letter queue can still be enabled, by using
- the ``deadletter_queue`` transport option::
+ the ``deadletter_queue`` transport option:
+
+ .. code-block:: pycon
>>> x = Connection('redis://',
... transport_options={'deadletter_queue': 'ae.undeliver'})
@@ -2824,7 +2872,9 @@ Fixes
The connections default channel will then be used.
- In addition shortcut methods has been added to Connection::
+ In addition shortcut methods has been added to Connection:
+
+ .. code-block:: pycon
>>> connection.Producer(exchange)
>>> connection.Consumer(queues=..., callbacks=...)
@@ -2929,11 +2979,15 @@ Fixes
* Broker connection info can be now be specified using URLs
- The broker hostname can now be given as an URL instead, of the format::
+ The broker hostname can now be given as an URL instead, of the format:
+
+ .. code-block:: text
transport://user:password@hostname:port/virtual_host
- for example the default broker is expressed as::
+ for example the default broker is expressed as:
+
+ .. code-block:: pycon
>>> Connection('amqp://guest:guest@localhost:5672//')
@@ -2947,11 +3001,15 @@ Fixes
forward-slash. This is necessary to distinguish between the virtual
host '' (empty) and '/', which are both acceptable virtual host names.
- A virtual host of '/' becomes:
+ A virtual host of '/' becomes::
+
+ .. code-block:: text
amqp://guest:guest@localhost:5672//
- and a virtual host of '' (empty) becomes::
+ and a virtual host of '' (empty) becomes:
+
+ .. code-block:: text
amqp://guest:guest@localhost:5672/
@@ -2960,7 +3018,9 @@ Fixes
* Now comes with default global connection and producer pools.
The acquire a connection using the connection parameters
- from a :class:`Connection`::
+ from a :class:`Connection`:
+
+ .. code-block:: pycon
>>> from kombu import Connection, connections
>>> connection = Connection('amqp://guest:guest@localhost//')
@@ -2968,7 +3028,9 @@ Fixes
... # do something with connection
To acquire a producer using the connection parameters
- from a :class:`Connection`::
+ from a :class:`Connection`:
+
+ .. code-block:: pycon
>>> from kombu import Connection, producers
>>> connection = Connection('amqp://guest:guest@localhost//')
@@ -2980,12 +3042,16 @@ Fixes
of producers is bound the same limit as number of connections.
The default limit of 100 connections per connection instance
- can be changed by doing::
+ can be changed by doing:
+
+ .. code-block:: pycon
>>> from kombu import pools
>>> pools.set_limit(10)
- The pool can also be forcefully closed by doing::
+ The pool can also be forcefully closed by doing:
+
+ .. code-block:: pycon
>>> from kombu import pools
>>> pool.reset()
@@ -3241,7 +3307,9 @@ Important Notes
the ``body_encoding`` property.
If you need to disable base64 encoding then you can do so
- via the transport options::
+ via the transport options:
+
+ .. code-block:: python
Connection(transport='...',
transport_options={'body_encoding': None})
@@ -3364,7 +3432,9 @@ Important Notes
* :envvar:`KOMBU_LOG_DEBUG` both enables channel logging and configures the
root logger to emit messages to standard error.
- **Example Usage**::
+ **Example Usage**:
+
+ .. code-block:: console
$ KOMBU_LOG_DEBUG=1 python
>>> from kombu import Connection
diff --git a/Makefile b/Makefile
index c05d1f33..1fee5313 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
PYTHON=python
SPHINX_DIR="docs/"
-SPHINX_BUILDDIR="${SPHINX_DIR}/.build"
+SPHINX_BUILDDIR="${SPHINX_DIR}/_build"
README="README.rst"
README_SRC="docs/templates/readme.txt"
CONTRIBUTING_SRC="docs/contributing.rst"
diff --git a/README.rst b/README.rst
index fdcbb75e..b892801c 100644
--- a/README.rst
+++ b/README.rst
@@ -28,7 +28,9 @@ Features
* High performance AMQP transport written in C - when using `librabbitmq`_
- This is automatically enabled if librabbitmq is installed::
+ This is automatically enabled if librabbitmq is installed:
+
+ .. code-block:: console
$ pip install librabbitmq
@@ -134,7 +136,7 @@ Kombu is using Sphinx, and the latest documentation can be found here:
Quick overview
--------------
-::
+.. code-block:: python
from kombu import Connection, Exchange, Queue
@@ -177,7 +179,9 @@ Quick overview
connection.drain_events()
-Or handle channels manually::
+Or handle channels manually:
+
+.. code-block:: python
with connection.channel() as channel:
producer = Producer(channel, ...)
@@ -185,7 +189,9 @@ Or handle channels manually::
All objects can be used outside of with statements too,
-just remember to close the objects after use::
+just remember to close the objects after use:
+
+.. code-block:: python
from kombu import Connection, Consumer, Producer
@@ -209,7 +215,7 @@ to a channel.
Binding exchanges and queues to a connection will make it use
that connections default channel.
-::
+.. code-block:: pycon
>>> exchange = Exchange('tasks', 'direct')
@@ -228,16 +234,22 @@ Installation
You can install `Kombu` either via the Python Package Index (PyPI)
or from source.
-To install using `pip`,::
+To install using `pip`,:
+
+.. code-block:: console
$ pip install kombu
-To install using `easy_install`,::
+To install using `easy_install`,:
+
+.. code-block:: console
$ easy_install kombu
If you have downloaded a source tarball you can install it
-by doing the following,::
+by doing the following,:
+
+.. code-block:: console
$ python setup.py build
# python setup.py install # as root
diff --git a/docs/.templates/sidebarintro.html b/docs/.templates/sidebarintro.html
deleted file mode 100644
index 09d6a33b..00000000
--- a/docs/.templates/sidebarintro.html
+++ /dev/null
@@ -1,7 +0,0 @@
-Kombu
-
- Kombu is a messaging library for Python.
-
-
- 
-
diff --git a/docs/.templates/sidebarlogo.html b/docs/.templates/sidebarlogo.html
deleted file mode 100644
index 6c398bad..00000000
--- a/docs/.templates/sidebarlogo.html
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
diff --git a/docs/Makefile b/docs/Makefile
index ef87680d..14b39e4b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,71 +5,219 @@
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
+BUILDDIR = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+ $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+.PHONY: help
help:
@echo "Please use \`make ' where is one of"
- @echo " html to make standalone HTML files"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " changes to make an overview over all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " applehelp to make an Apple Help Book"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " epub3 to make an epub3"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " coverage to run coverage check of the documentation (if enabled)"
+.PHONY: clean
clean:
- -rm -rf .build/*
+ rm -rf $(BUILDDIR)/*
+.PHONY: html
html:
- mkdir -p .build/html .build/doctrees
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
- @echo "Build finished. The HTML pages are in .build/html."
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+.PHONY: dirhtml
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
pickle:
- mkdir -p .build/pickle .build/doctrees
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
-web: pickle
-
+.PHONY: json
json:
- mkdir -p .build/json .build/doctrees
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
+.PHONY: htmlhelp
htmlhelp:
- mkdir -p .build/htmlhelp .build/doctrees
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in .build/htmlhelp."
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+.PHONY: qthelp
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PROJ.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PROJ.qhc"
+
+.PHONY: applehelp
+applehelp:
+ $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+ @echo
+ @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+ @echo "N.B. You won't be able to view it unless you put it in" \
+ "~/Library/Documentation/Help or install it in your application" \
+ "bundle."
+
+.PHONY: devhelp
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/PROJ"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PROJ"
+ @echo "# devhelp"
+
+.PHONY: epub
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+ $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+ @echo
+ @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
latex:
- mkdir -p .build/latex .build/doctrees
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
- @echo "Build finished; the LaTeX files are in .build/latex."
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
- "run these through (pdf)latex."
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+.PHONY: latexpdf
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
changes:
- mkdir -p .build/changes .build/doctrees
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
- @echo "The overview file is in .build/changes."
+ @echo "The overview file is in $(BUILDDIR)/changes."
+.PHONY: linkcheck
linkcheck:
- mkdir -p .build/linkcheck .build/doctrees
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
- "or in .build/linkcheck/output.txt."
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+ $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+ @echo "Testing of coverage in the sources finished, look at the " \
+ "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/docs/.static/.keep b/docs/_static/.keep
similarity index 100%
rename from docs/.static/.keep
rename to docs/_static/.keep
diff --git a/docs/_templates/sidebardonations.html b/docs/_templates/sidebardonations.html
new file mode 100644
index 00000000..90c930be
--- /dev/null
+++ b/docs/_templates/sidebardonations.html
@@ -0,0 +1,10 @@
+
diff --git a/docs/_theme/celery/static/celery.css_t b/docs/_theme/celery/static/celery.css_t
deleted file mode 100644
index 4274f31f..00000000
--- a/docs/_theme/celery/static/celery.css_t
+++ /dev/null
@@ -1,394 +0,0 @@
-/*
- * celery.css_t
- * ~~~~~~~~~~~~
- *
- * :copyright: Copyright 2010 by Armin Ronacher.
- * :license: BSD, see LICENSE for details.
- */
-
-{% set page_width = 940 %}
-{% set sidebar_width = 220 %}
-{% set body_font_stack = 'Optima, Segoe, "Segoe UI", Candara, Calibri, Arial, sans-serif' %}
-{% set headline_font_stack = 'Futura, "Trebuchet MS", Arial, sans-serif' %}
-{% set code_font_stack = "'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace" %}
-
-@import url("basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
- align: left;
- font-family: {{ body_font_stack }};
- font-size: 17px;
- background-color: white;
- color: #000;
- margin: 30px 0 0 0;
- padding: 0;
-}
-
-div.document {
- width: {{ page_width }}px;
- margin: 0 auto;
-}
-
-div.related {
- width: {{ page_width - 20 }}px;
- padding: 5px 10px;
- background: #F2FCEE;
- margin: 15px auto 15px auto;
-}
-
-div.documentwrapper {
- float: left;
- width: 100%;
-}
-
-div.bodywrapper {
- margin: 0 0 0 {{ sidebar_width }}px;
-}
-
-div.sphinxsidebar {
- width: {{ sidebar_width }}px;
-}
-
-hr {
- border: 1px solid #B1B4B6;
-}
-
-div.body {
- background-color: #ffffff;
- color: #3E4349;
- padding: 0 30px 0 30px;
-}
-
-img.celerylogo {
- padding: 0 0 10px 10px;
- float: right;
-}
-
-div.footer {
- width: {{ page_width - 15 }}px;
- margin: 10px auto 30px auto;
- padding-right: 15px;
- font-size: 14px;
- color: #888;
- text-align: right;
-}
-
-div.footer a {
- color: #888;
-}
-
-div.sphinxsidebar a {
- color: #444;
- text-decoration: none;
- border-bottom: 1px dashed #DCF0D5;
-}
-
-div.sphinxsidebar a:hover {
- border-bottom: 1px solid #999;
-}
-
-div.sphinxsidebar {
- font-size: 14px;
- line-height: 1.5;
-}
-
-div.sphinxsidebarwrapper {
- padding: 7px 10px;
-}
-
-div.sphinxsidebarwrapper p.logo {
- padding: 0 0 20px 0;
- margin: 0;
-}
-
-div.sphinxsidebar h3,
-div.sphinxsidebar h4 {
- font-family: {{ headline_font_stack }};
- color: #444;
- font-size: 24px;
- font-weight: normal;
- margin: 0 0 5px 0;
- padding: 0;
-}
-
-div.sphinxsidebar h4 {
- font-size: 20px;
-}
-
-div.sphinxsidebar h3 a {
- color: #444;
-}
-
-div.sphinxsidebar p.logo a,
-div.sphinxsidebar h3 a,
-div.sphinxsidebar p.logo a:hover,
-div.sphinxsidebar h3 a:hover {
- border: none;
-}
-
-div.sphinxsidebar p {
- color: #555;
- margin: 10px 0;
-}
-
-div.sphinxsidebar ul {
- margin: 10px 0;
- padding: 0;
- color: #000;
-}
-
-div.sphinxsidebar input {
- border: 1px solid #ccc;
- font-family: {{ body_font_stack }};
- font-size: 1em;
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-a {
- color: #348613;
- text-decoration: underline;
-}
-
-a:hover {
- color: #59B833;
- text-decoration: underline;
-}
-
-div.body h1,
-div.body h2,
-div.body h3,
-div.body h4,
-div.body h5,
-div.body h6 {
- font-family: {{ headline_font_stack }};
- font-weight: normal;
- margin: 30px 0px 10px 0px;
- padding: 0;
-}
-
-div.body h1 { margin-top: 0; padding-top: 0; font-size: 200%; }
-div.body h2 { font-size: 180%; }
-div.body h3 { font-size: 150%; }
-div.body h4 { font-size: 130%; }
-div.body h5 { font-size: 100%; }
-div.body h6 { font-size: 100%; }
-
-div.body h1 a.toc-backref,
-div.body h2 a.toc-backref,
-div.body h3 a.toc-backref,
-div.body h4 a.toc-backref,
-div.body h5 a.toc-backref,
-div.body h6 a.toc-backref {
- color: inherit!important;
- text-decoration: none;
-}
-
-a.headerlink {
- color: #ddd;
- padding: 0 4px;
- text-decoration: none;
-}
-
-a.headerlink:hover {
- color: #444;
- background: #eaeaea;
-}
-
-div.body p, div.body dd, div.body li {
- line-height: 1.4em;
-}
-
-div.admonition {
- background: #fafafa;
- margin: 20px -30px;
- padding: 10px 30px;
- border-top: 1px solid #ccc;
- border-bottom: 1px solid #ccc;
-}
-
-div.admonition p.admonition-title {
- font-family: {{ headline_font_stack }};
- font-weight: normal;
- font-size: 24px;
- margin: 0 0 10px 0;
- padding: 0;
- line-height: 1;
-}
-
-div.admonition p.last {
- margin-bottom: 0;
-}
-
-div.highlight{
- background-color: white;
-}
-
-dt:target, .highlight {
- background: #FAF3E8;
-}
-
-div.note {
- background-color: #eee;
- border: 1px solid #ccc;
-}
-
-div.seealso {
- background-color: #ffc;
- border: 1px solid #ff6;
-}
-
-div.topic {
- background-color: #eee;
-}
-
-div.warning {
- background-color: #ffe4e4;
- border: 1px solid #f66;
-}
-
-p.admonition-title {
- display: inline;
-}
-
-p.admonition-title:after {
- content: ":";
-}
-
-pre, tt {
- font-family: {{ code_font_stack }};
- font-size: 0.9em;
-}
-
-img.screenshot {
-}
-
-tt.descname, tt.descclassname {
- font-size: 0.95em;
-}
-
-tt.descname {
- padding-right: 0.08em;
-}
-
-img.screenshot {
- -moz-box-shadow: 2px 2px 4px #eee;
- -webkit-box-shadow: 2px 2px 4px #eee;
- box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils {
- border: 1px solid #888;
- -moz-box-shadow: 2px 2px 4px #eee;
- -webkit-box-shadow: 2px 2px 4px #eee;
- box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils td, table.docutils th {
- border: 1px solid #888;
- padding: 0.25em 0.7em;
-}
-
-table.field-list, table.footnote {
- border: none;
- -moz-box-shadow: none;
- -webkit-box-shadow: none;
- box-shadow: none;
-}
-
-table.footnote {
- margin: 15px 0;
- width: 100%;
- border: 1px solid #eee;
- background: #fdfdfd;
- font-size: 0.9em;
-}
-
-table.footnote + table.footnote {
- margin-top: -15px;
- border-top: none;
-}
-
-table.field-list th {
- padding: 0 0.8em 0 0;
-}
-
-table.field-list td {
- padding: 0;
-}
-
-table.footnote td.label {
- width: 0px;
- padding: 0.3em 0 0.3em 0.5em;
-}
-
-table.footnote td {
- padding: 0.3em 0.5em;
-}
-
-dl {
- margin: 0;
- padding: 0;
-}
-
-dl dd {
- margin-left: 30px;
-}
-
-blockquote {
- margin: 0 0 0 30px;
- padding: 0;
-}
-
-ul {
- margin: 10px 0 10px 30px;
- padding: 0;
-}
-
-pre {
- background: #F0FFEB;
- padding: 7px 10px;
- margin: 15px 0;
- border: 1px solid #C7ECB8;
- border-radius: 2px;
- -moz-border-radius: 2px;
- -webkit-border-radius: 2px;
- line-height: 1.3em;
-}
-
-tt {
- background: #F0FFEB;
- color: #222;
- /* padding: 1px 2px; */
-}
-
-tt.xref, a tt {
- background: #F0FFEB;
- border-bottom: 1px solid white;
-}
-
-a.reference {
- text-decoration: none;
- border-bottom: 1px dashed #DCF0D5;
-}
-
-a.reference:hover {
- border-bottom: 1px solid #6D4100;
-}
-
-a.footnote-reference {
- text-decoration: none;
- font-size: 0.7em;
- vertical-align: top;
- border-bottom: 1px dashed #DCF0D5;
-}
-
-a.footnote-reference:hover {
- border-bottom: 1px solid #6D4100;
-}
-
-a:hover tt {
- background: #EEE;
-}
diff --git a/docs/_theme/celery/theme.conf b/docs/_theme/celery/theme.conf
deleted file mode 100644
index 9ad052cc..00000000
--- a/docs/_theme/celery/theme.conf
+++ /dev/null
@@ -1,5 +0,0 @@
-[theme]
-inherit = basic
-stylesheet = celery.css
-
-[options]
diff --git a/docs/conf.py b/docs/conf.py
index 7061e8a9..45f17cbe 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,129 +1,23 @@
# -*- coding: utf-8 -*-
from __future__ import absolute_import, unicode_literals
-import sys
-import os
-
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-sys.path.append('_ext')
-sys.path.append(os.path.join(os.pardir, 'tests'))
-import kombu # noqa
-
-from django.conf import settings # noqa
-if not settings.configured:
- settings.configure()
-try:
- from django import setup as django_setup
-except ImportError:
- pass
-else:
- django_setup()
-
-# General configuration
-# ---------------------
-
-extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.coverage',
- 'sphinx.ext.viewcode',
- 'sphinx.ext.imgmath',
- 'sphinxcontrib.cheeseshop',
- 'githubsphinx',
-]
-
-LINKCODE_URL = 'https://github.com/{proj}/tree/{branch}/{filename}.py'
-GITHUB_PROJECT = 'celery/kombu'
-GITHUB_BRANCH = 'master'
-
-
-def linkcode_resolve(domain, info):
- if domain != 'py' or not info['module']:
- return
- filename = info['module'].replace('.', '/')
- return LINKCODE_URL.format(
- proj=GITHUB_PROJECT,
- branch=GITHUB_BRANCH,
- filename=filename,
- )
-
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'Kombu'
-copyright = '2009-2016, Ask Solem'
-
-# 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 = '.'.join(map(str, kombu.VERSION[0:2]))
-# The full version, including alpha/beta/rc tags.
-release = kombu.__version__
-
-exclude_trees = ['.build']
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-add_function_parentheses = True
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'colorful'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
-
-html_use_smartypants = True
-
-# If false, no module index is generated.
-html_use_modindex = True
-
-# If false, no index is generated.
-html_use_index = True
-
-latex_documents = [
- ('index', 'Kombu.tex', 'Kombu Documentation',
- 'Ask Solem', 'manual'),
-]
-
-html_theme = 'celery'
-html_theme_path = ['_theme']
-html_sidebars = {
- 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
- '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html',
- 'sourcelink.html', 'searchbox.html'],
-}
-
-# ## Issuetracker
-
-github_project = GITHUB_PROJECT
-
-intersphinx_mapping = {
- 'python': ('http://docs.python.org/dev', None),
- 'celery': ('http://docs.celeryproject.org/en/latest', None),
- 'djcelery': ('http://django-celery.readthedocs.org/en/latest', None),
- 'cyme': ('http://cyme.readthedocs.org/en/latest', None),
- 'amqp': ('http://amqp.readthedocs.org/en/latest', None),
- 'vine': ('http://vine.readthedocs.org/en/latest', None),
- 'redis': ('http://redis-py.readthedocs.org/en/latest', None),
- 'django': ('http://django.readthedocs.org/en/latest', None),
- 'boto': ('http://boto.readthedocs.org/en/latest', None),
- 'sqlalchemy': ('http://sqlalchemy.readthedocs.org/en/latest', None),
- 'kazoo': ('http://kazoo.readthedocs.org/en/latest', None),
- 'pyzmq': ('http://pyzmq.readthedocs.org/en/latest', None),
- 'msgpack': ('http://pythonhosted.org/msgpack-python/', None),
- 'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
-}
+from sphinx_celery import conf
+globals().update(conf.build_config(
+ 'kombu', __file__,
+ project='Kombu',
+ version_dev='4.0',
+ version_stable='3.0',
+ canonical_url='http://docs.kombu.me',
+ webdomain='kombu.me',
+ github_project='celery/kombu',
+ author='Ask Solem & contributors',
+ author_name='Ask Solem',
+ copyright='2009-2016',
+ publisher='Celery Project',
+ html_logo='images/kombusmall.jpg',
+ html_favicon='images/favicon.ico',
+ html_prepend_sidebars=['sidebardonations.html'],
+ extra_extensions=[],
+ configure_django_settings={'DEBUG': False},
+))
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
new file mode 100644
index 00000000..8df5f22d
Binary files /dev/null and b/docs/images/favicon.ico differ
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 00000000..a75aa4e2
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,272 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^` where ^ is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. epub3 to make an epub3
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ echo. coverage to run coverage check of the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 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.http://sphinx-doc.org/
+ exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PROJ.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PROJ.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "epub3" (
+ %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub3 file is in %BUILDDIR%/epub3.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %~dp0
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %~dp0
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+if "%1" == "coverage" (
+ %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+ goto end
+)
+
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
+:end
diff --git a/docs/userguide/connections.rst b/docs/userguide/connections.rst
index daec191b..0e174e81 100644
--- a/docs/userguide/connections.rst
+++ b/docs/userguide/connections.rst
@@ -13,7 +13,9 @@ To send and receive messages you need a transport and a connection.
There are several transports to choose from (amqp, librabbitmq, redis, qpid, in-memory, etc.),
and you can even create your own. The default transport is amqp.
-Create a connection using the default transport::
+Create a connection using the default transport:
+
+.. code-block:: pycon
>>> from kombu import Connection
>>> connection = Connection('amqp://guest:guest@localhost:5672//')
@@ -21,23 +23,31 @@ Create a connection using the default transport::
The connection will not be established yet, as the connection is established
when needed. If you want to explicitly establish the connection
you have to call the :meth:`~kombu.Connection.connect`
-method::
+method:
+
+.. code-block:: pycon
>>> connection.connect()
-You can also check whether the connection is connected::
+You can also check whether the connection is connected:
+
+.. code-block:: pycon
>>> connection.connected
True
-Connections must always be closed after use::
+Connections must always be closed after use:
+
+.. code-block:: pycon
>>> connection.close()
But best practice is to release the connection instead,
this will release the resource if the connection is associated
with a connection pool, or close the connection if not,
-and makes it easier to do the transition to connection pools later::
+and makes it easier to do the transition to connection pools later:
+
+.. code-block:: pycon
>>> connection.release()
@@ -47,7 +57,9 @@ and makes it easier to do the transition to connection pools later::
Of course, the connection can be used as a context, and you are
encouraged to do so as it makes it harder to forget releasing open
-resources::
+resources:
+
+.. code-block:: python
with Connection() as connection:
# work with connection
@@ -57,11 +69,15 @@ resources::
URLs
====
-Connection parameters can be provided as an URL in the format::
+Connection parameters can be provided as an URL in the format:
+
+.. code-block:: text
transport://userid:password@hostname:port/virtual_host
-All of these are valid URLs::
+All of these are valid URLs:
+
+.. code-block:: text
# Specifies using the amqp transport only, default values
# are taken from the keyword arguments.
@@ -82,7 +98,9 @@ All of these are valid URLs::
# Using virtual host 'foo'
amqp://localhost/foo
-The query part of the URL can also be used to set options, e.g.::
+The query part of the URL can also be used to set options, e.g.:
+
+.. code-block:: text
amqp://localhost/myvhost?ssl=1
@@ -91,7 +109,9 @@ See :ref:`connection-options` for a list of supported options.
A connection without options will use the default connection settings,
which is using the localhost host, default port, user name `guest`,
password `guest` and virtual host "/". A connection without arguments
-is the same as::
+is the same as:
+
+.. code-block:: pycon
>>> Connection('amqp://guest:guest@localhost:5672//')
diff --git a/docs/userguide/consumers.rst b/docs/userguide/consumers.rst
index 7a513f5a..e76a88b6 100644
--- a/docs/userguide/consumers.rst
+++ b/docs/userguide/consumers.rst
@@ -18,7 +18,9 @@ drain events from all channels on that connection.
Kombu since 3.0 will only accept json/binary or text messages by default,
to allow deserialization of other formats you have to specify them
- in the ``accept`` argument::
+ in the ``accept`` argument:
+
+ .. code-block:: python
Consumer(conn, accept=['json', 'pickle', 'msgpack', 'yaml'])
diff --git a/docs/userguide/pools.rst b/docs/userguide/pools.rst
index 69d3acba..3c4b9d81 100644
--- a/docs/userguide/pools.rst
+++ b/docs/userguide/pools.rst
@@ -29,7 +29,9 @@ This is a pool group, which means you give it a connection instance,
and you get a pool instance back. We have one pool per connection
instance to support multiple connections in the same app.
All connection instances with the same connection parameters will
-get the same pool::
+get the same pool:
+
+.. code-block:: pycon
>>> from kombu import Connection
>>> from kombu.pools import connections
@@ -124,7 +126,9 @@ By default every connection instance has a limit of 200 connections.
You can change this limit using :func:`kombu.pools.set_limit`.
You are able to grow the pool at runtime, but you can't shrink it,
so it is best to set the limit as early as possible after your application
-starts::
+starts:
+
+.. code-block:: pycon
>>> from kombu import pools
>>> pools.set_limit()
diff --git a/docs/userguide/serialization.rst b/docs/userguide/serialization.rst
index 5ef3738e..799c565c 100644
--- a/docs/userguide/serialization.rst
+++ b/docs/userguide/serialization.rst
@@ -85,13 +85,17 @@ Each option has its advantages and disadvantages.
To instruct `Kombu` to use an alternate serialization method,
use one of the following options.
- 1. Set the serialization option on a per-producer basis::
+ 1. Set the serialization option on a per-producer basis:
+
+ .. code-block:: pycon
>>> producer = Producer(channel,
... exchange=exchange,
... serializer='yaml')
- 2. Set the serialization option per message::
+ 2. Set the serialization option per message:
+
+ .. code-block:: pycon
>>> producer.publish(message, routing_key=rkey,
... serializer='pickle')
@@ -110,7 +114,9 @@ pass in a plain string or Unicode object as your message and a custom `content_t
not waste cycles serializing/deserializing the data.
You can optionally specify a `content_encoding`
-for the raw data::
+for the raw data:
+
+.. code-block:: pycon
>>> with open('~/my_picture.jpg', 'rb') as fh:
... producer.publish(fh.read(),
diff --git a/docs/userguide/simple.rst b/docs/userguide/simple.rst
index 4cf98ec6..c65d72c8 100644
--- a/docs/userguide/simple.rst
+++ b/docs/userguide/simple.rst
@@ -21,7 +21,7 @@ a :class:`~kombu.Queue` as the name argument instead.
In addition, the :class:`~kombu.Connection` comes with
shortcuts to create simple queues using the current connection:
-.. code-block:: python
+.. code-block:: pycon
>>> queue = connection.SimpleQueue('myqueue')
>>> # ... do something with queue
@@ -30,7 +30,7 @@ shortcuts to create simple queues using the current connection:
This is equivalent to:
-.. code-block:: python
+.. code-block:: pycon
>>> from kombu import SimpleQueue, SimpleBuffer
diff --git a/extra/doc2ghpages b/extra/doc2ghpages
deleted file mode 100755
index 5ebc7aaa..00000000
--- a/extra/doc2ghpages
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/bash
-
-git checkout master
-(cd docs;
- rm -rf .build;
- make html;
- (cd .build/html;
- sphinx-to-github;))
-git checkout gh-pages
-cp -r docs/.build/html/* .
-git commit . -m "Autogenerated documentation for github."
-git push origin gh-pages
-git checkout master
diff --git a/requirements/docs.txt b/requirements/docs.txt
index 8be782f1..d9c105cf 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -1,4 +1,3 @@
-Sphinx>=1.4
-sphinxcontrib-cheeseshop
+sphinx_celery
Django
-r extras/mongodb.txt
diff --git a/setup.cfg b/setup.cfg
index 95a4f0d6..322bd056 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -5,12 +5,9 @@ where = kombu/tests
[build_sphinx]
source-dir = docs/
-build-dir = docs/.build
+build-dir = docs/_build
all_files = 1
-[upload_sphinx]
-upload-dir = docs/.build/html
-
[bdist_rpm]
requires = amqp >= 1.4.5