adding sphinx docs

python-arq · Aug 14, 2016 · e6a6901 · e6a6901
1 parent 45fee40
commit e6a6901
Show file tree

Hide file tree

Showing 15 changed files with 602 additions and 5 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,17 @@
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.rst]
+indent_style = space
+indent_size = 4
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,4 @@ htmlcov/
 /dist
 test.py
 *.egg-info
+docs/_build/
diff --git a/.travis.yml b/.travis.yml
@@ -9,6 +9,7 @@ install:
 script:
 - make lint
 - make test
+- make docs
 after_success:
 - codecov
 deploy:

diff --git a/Makefile b/Makefile
@@ -1,26 +1,32 @@
+.PHONY: install
 install:
 	pip install -U pip
 	pip install -e .
 	pip install -Ur tests/requirements.txt
 
+.PHONY: isort
 isort:
 	isort -rc -w 120 arq
 	isort -rc -w 120 tests
 
-
+.PHONY: lint
 lint:
 	python setup.py check -rms
 	flake8 arq/ tests/
 	./tests/isort_test.sh
 
+.PHONY: test
 test:
 	py.test --cov=arq && coverage combine
 
+.PHONY: .test-build-cov
 .test-build-cov:
 	py.test --cov=arq && (echo "building coverage html"; coverage combine; coverage html)
 
+.PHONY: all
 all: .test-build-cov lint
 
+.PHONY: clean
 clean:
 	rm -rf `find . -name __pycache__`
 	rm -f `find . -type f -name '*.py[co]' `
@@ -35,8 +41,7 @@ clean:
 	make -C docs clean
 	python setup.py clean
 
-doc:
+.PHONY: docs
+docs:
 	make -C docs html
 	@echo "open file://`pwd`/docs/_build/html/index.html"
-
-.PHONY: install isort lint test .test-build-cov all clean doc
diff --git a/arq/jobs.py b/arq/jobs.py
@@ -1,3 +1,7 @@
+"""
+:mod:`jobs`
+===========
+"""
 from datetime import datetime
 
 import msgpack

diff --git a/arq/logs.py b/arq/logs.py
@@ -1,3 +1,7 @@
+"""
+:mod:`logs`
+===========
+"""
 import logging
 import re
 

diff --git a/arq/main.py b/arq/main.py
@@ -1,3 +1,7 @@
+"""
+:mod:`main`
+===========
+"""
 import inspect
 import logging
 from functools import wraps
@@ -20,7 +24,7 @@ def __new__(mcs, cls, bases, classdict):
 
 class Actor(RedisMixin, metaclass=ActorMeta):
     """
-    All classes which to to arq should inherit from Actor.
+    All classes which wish to use arq should inherit from Actor.
 
     Actor defines three default queues: HIGH_QUEUE, DEFAULT_QUEUE and LOW_QUEUE which are processed
     in that order of priority by the worker.

diff --git a/arq/testing.py b/arq/testing.py
@@ -1,3 +1,7 @@
+"""
+:mod:`testing`
+==============
+"""
 import asyncio
 import contextlib
 import io

diff --git a/arq/utils.py b/arq/utils.py
@@ -1,3 +1,7 @@
+"""
+:mod:`utilities`
+================
+"""
 import asyncio
 import base64
 import os

diff --git a/arq/worker.py b/arq/worker.py
@@ -1,3 +1,7 @@
+"""
+:mod:`worker`
+=============
+"""
 import asyncio
 import logging
 import os

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,45 @@
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@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 $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "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."
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,3 +11,4 @@ htmlcov/ @@
     /dist
     test.py
     *.egg-info
+    docs/_build/