Merge pull request #33 from wsanchez/docs

Add documentation to build

.travis.yml

@@ -16,7 +16,13 @@ install:
 matrix:
   include:
     - python: 3.5
-      env: TOXENV=flake8,mypy
+      env: TOXENV=flake8
+
+    - python: 3.5
+      env: TOXENV=mypy
+
+    - python: 3.5
+      env: TOXENV=docs
 
     - python: 3.5
       env: TOXENV=py35-coverage,coverage_codecov

bin/develop

@@ -109,17 +109,11 @@ venv_init () {
 
   echo "Installing Tox...";
   "${python}" -m pip install --upgrade tox;
-
-  echo "Installing mock...";
-  "${python}" -m pip install --upgrade mock;
-
-  echo "Installing Hypothesis...";
-  "${python}" -m pip install --upgrade hypothesis;
 }
 
 venv_install_requirements () {
   echo "Installing required packages...";
-  "${python}" -m pip install --requirement "${wd}/requirements.txt";
+  "${python}" -m pip install --requirement "${wd}/requirements-dev.txt";
 }
 
 

docs/conf.py

@@ -0,0 +1,45 @@
+extensions = ["sphinx.ext.autodoc"]
+
+# Project info
+
+project = "sample-klein-app"
+copyright = "2016-2017"
+author = u"Wilfredo S\xe1nchez Vega"
+
+# File names
+
+templates_path = []
+html_static_path = []
+source_suffix = [".rst", ".md"]
+master_doc = "index"
+exclude_patterns = []
+
+# Styling
+
+html_theme = "sphinx_rtd_theme"
+
+# Pedantry
+
+nitpicky = True
+nitpick_ignore = [
+    # Bugs in Python documentation
+    ("py:class", "float"     ),
+    ("py:class", "int"       ),
+    ("py:class", "object"    ),
+    ("py:class", "Union"     ),
+    ("py:data" , "sys.argv"  ),
+    ("py:exc"  , "ValueError"),
+    ("py:obj"  , "None"      ),
+
+    # Need to learn how to intersphinx with Twisted
+    ("py:class", "twisted.internet.defer.Deferred"                           ),
+    ("py:class", "twisted.trial._synctest.SynchronousTestCase"               ),
+    ("py:class", "twisted.trial.unittest.SynchronousTestCase"                ),
+    ("py:class", "twisted.trial.unittest.TestCase"                           ),
+    ("py:const", "twisted.web.http.NOT_FOUND"                                ),
+    ("py:meth" , "twisted.trial.unittest.SynchronousTestCase.successResultOf"),
+    ("py:mod"  , "twisted.trial.unittest"                                    ),
+
+    # Need to learn how to intersphinx with Klein
+    ("py:class", "klein.app.Klein"),
+]

docs/index.rst

@@ -0,0 +1,16 @@
+Sample Klein Application
+========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   sample_klein_app
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+mock
+hypothesis

setup.py

@@ -95,7 +95,7 @@
 
 def main():
     """
-    Run L{setup}.
+    Run :func:`setup`.
     """
     setup(
         name=name,

src/sample_klein_app/application/_main.py

@@ -2,17 +2,16 @@
 Shared main function.
 """
 
-import sys
 from typing import Sequence
 
 
-def main(applicationClass, argv: Sequence[str] = sys.argv) -> None:
+def main(applicationClass, argv: Sequence[str] = None) -> None:
     """
     Executable entry point
 
-    @param applicationClass: A Klein application to run.
+    :param applicationClass: A Klein application to run.
 
-    @param argv: Command line arguments.
+    :param argv: Command line arguments.  If :obj:`None`, use :data:`sys.argv`.
     """
     application = applicationClass()
     application.router.run("localhost", 8080)

src/sample_klein_app/application/composite.py

@@ -35,7 +35,7 @@ def root(self, request: IRequest) -> KleinRenderable:
 
         Responds with a message noting the nature of the application.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return "This is a web application composed from multiple applications."
 
@@ -44,9 +44,9 @@ def dns(self, request: IRequest) -> KleinRenderable:
         """
         DNS application resource.
 
-        Routes requests to L{DNSApplication}.
+        Routes requests to :class:`.dns.Application`.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return DNSApplication().router.resource()
 
@@ -55,9 +55,9 @@ def hello(self, request: IRequest) -> KleinRenderable:
         """
         Hello application resource.
 
-        Routes requests to L{HelloApplication}.
+        Routes requests to :class:`.hello.Application`.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return HelloApplication().router.resource()
 
@@ -66,9 +66,9 @@ def math(self, request: IRequest) -> KleinRenderable:
         """
         Math application resource.
 
-        Routes requests to L{MathApplication}.
+        Routes requests to :class:`.math.Application`.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return MathApplication().router.resource()
 

src/sample_klein_app/application/dns.py

@@ -35,7 +35,7 @@ def root(self, request: IRequest) -> KleinRenderable:
 
         Responds with a message noting the nature of the application.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return "DNS API."
 
@@ -47,9 +47,9 @@ async def hostname(self, request: IRequest, name: str) -> KleinRenderable:
         Performs a lookup on the given name and responds with the resulting
         address.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param name: A host name.
+        :param name: A host name.
         """
         try:
             address = await getHostByName(name)

src/sample_klein_app/application/hello.py

@@ -31,7 +31,7 @@ def hello(self, request: IRequest) -> KleinRenderable:
 
         Responds with a message noting the nature of the application.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return "Hello!"
 

src/sample_klein_app/application/klein.py

@@ -7,7 +7,7 @@
 from twisted.web.iweb import IRenderable
 from twisted.web.resource import IResource
 
-from klein import Klein
+from klein import Klein as SuperKlein
 
 
 __all__ = (
@@ -18,3 +18,15 @@
 
 # Expected return types for route methods
 KleinRenderable = Union[str, IResource, IRenderable]
+
+
+#
+# Subclass Klein so that we can override its documentation to work with Sphinx;
+# Klein uses epydoc syntax, which is not compatible, and because the router
+# is an attribute of each application, its doc string shows up in our
+# documentation.
+#
+class Klein(SuperKlein):
+    """
+    Request router.
+    """

src/sample_klein_app/application/math.py

@@ -34,7 +34,7 @@ def root(self, request: IRequest) -> KleinRenderable:
 
         Responds with a message noting the nature of the application.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
         """
         return "Math happens here."
 
@@ -45,11 +45,11 @@ def add(self, request: IRequest, a: str, b: str) -> KleinRenderable:
 
         Adds the two given numbers and responds with the result.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param a: A number to add to C{b}.
+        :param a: A number to add to ``b``.
 
-        @param b: A number to add to C{a}.
+        :param b: A number to add to ``a``.
         """
         x = self.numberify(a) + self.numberify(b)  # type: ignore #see #21
         return "{}".format(x)
@@ -62,11 +62,11 @@ def subtract(self, request: IRequest, a: str, b: str) -> KleinRenderable:
         Subtracts one of two given numbers from the other and responds with the
         result.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param a: A number to subtract C{b} from.
+        :param a: A number to subtract ``b`` from.
 
-        @param b: A number to subtract from C{a}.
+        :param b: A number to subtract from ``a``.
         """
         x = self.numberify(a) - self.numberify(b)  # type: ignore #see #21
         return "{}".format(x)
@@ -78,11 +78,11 @@ def multiply(self, request: IRequest, a: str, b: str) -> KleinRenderable:
 
         Multiplies the two given numbers and responds with the result.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param a: A number to multiply with C{b}.
+        :param a: A number to multiply with ``b``.
 
-        @param b: A number to multiply with C{a}.
+        :param b: A number to multiply with ``a``.
         """
         x = self.numberify(a) * self.numberify(b)  # type: ignore #see #21
         return "{}".format(x)
@@ -95,23 +95,23 @@ def divide(self, request: IRequest, a: str, b: str) -> KleinRenderable:
         Divides one of two given numbers from the other and responds with the
         result.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param a: A number to divide by C{b}.
+        :param a: A number to divide by ``b``.
 
-        @param b: A number to divide C{a} by.
+        :param b: A number to divide ``a`` by.
         """
         x = self.numberify(a) / self.numberify(b)  # type: ignore #see #21
         return "{}".format(x)
 
     @router.handle_errors(ValueError)
     def valueError(self, request: IRequest, failure) -> KleinRenderable:
         """
-        Error handler for L{ValueError}.
+        Error handler for :exc:`ValueError`.
 
-        @param request: The request to respond to.
+        :param request: The request to respond to.
 
-        @param failure: The failure that occurred.
+        :param failure: The failure that occurred.
         """
         request.setResponseCode(http.BAD_REQUEST)
         return "Invalid inputs provided."
@@ -121,7 +121,7 @@ def numberify(string: str) -> Union[int, float]:
         """
         Convert a string into a number.
 
-        @param string: A string to convert into a number.
+        :param string: A string to convert into a number.
         """
         try:
             return int(string)

src/sample_klein_app/application/test/__init__.py

@@ -1,3 +1,3 @@
 """
-Tests for L{sample_klein_app.application}.
+Tests for :mod:`sample_klein_app.application`.
 """

src/sample_klein_app/application/test/mock_render.py

@@ -26,15 +26,15 @@ async def assertResponse(
     Generate and process a request using the given application and assert
     that the response is as expected.
 
-    @param application: The application to route the request to.
+    :param application: The application to route the request to.
 
-    @param request_path: The path portion of the request URI.
+    :param request_path: The path portion of the request URI.
 
-    @param response_code: The expected HTTP status code for the response.
+    :param response_code: The expected HTTP status code for the response.
 
-    @param response_data: The expected HTTP entity body data for the response.
+    :param response_data: The expected HTTP entity body data for the response.
 
-    @param response_location_path: The expected C{"Location"} HTTP header value
+    :param response_location_path: The expected ``Location`` HTTP header value
         for the response.
     """
     request = mock_request(request_path)
@@ -64,9 +64,9 @@ async def render(application, request: IRequest) -> None:
     """
     Render a response from the given application for the given request.
 
-    @param application: The application to route the request to.
+    :param application: The application to route the request to.
 
-    @param request: The request to route the request to the application.
+    :param request: The request to route the request to the application.
     """
     resource = application.router.resource()
     await _render(resource, request, notifyFinish=True)