fixed a bunch of documentation warnings

CHANGES.rst

@@ -29,19 +29,19 @@ v10.0.0
   Use this functionality from the portend package directly.
 
 v9.0.0
------
+------
 
 * #1481: Move functionality from cherrypy.wsgiserver to
   the `cheroot 5.0 <https://pypi.org/project/Cheroot/5.0.1/>`_
   project.
 
 v8.9.1
------
+------
 
 * #1537: Restore dependency on pywin32 for Python 3.6.
 
 v8.9.0
------
+------
 
 * #1547: Replaced ``cherryd`` distutils script with a setuptools
   console entry point.
@@ -52,17 +52,17 @@ v8.9.0
   a ticket with the project.
 
 v8.8.0
------
+------
 
 * #1528: Allow a timeout of 0 to server.
 
 v8.7.0
------
+------
 
 * #645: Setting a bind port of 0 will bind to an ephemeral port.
 
 v8.6.0
------
+------
 
 * #1538 and #1090: Removed cruft from the setup script and
   instead rely on `include_package_data
@@ -72,7 +72,7 @@ v8.6.0
   be included in the installed package.
 
 v8.5.0
------
+------
 
 * The pyOpenSSL support is now included on Python 3 builds,
   removing the last disparity between Python 2 and Python 3
@@ -81,44 +81,44 @@ v8.5.0
   builds, as reported in #1149.
 
 v8.4.0
------
+------
 
 * #1532: Also release wheels for Python 2, enabling
   offline installation.
 
 v8.3.1
------
+------
 
 * #1537: Disable dependency on pypiwin32 on Python 3.6
   until a viable build of pypiwin32 can be made on that
   Python version.
 
 v8.3.0
------
+------
 
 * Consolidated some documentation and include the more
   concise readme in the package long description, as found
   on PyPI.
 
 v8.2.0
------
+------
 
 * #1463: CherryPy tests are now run under pytest and
   invoked using tox.
 
 v8.1.3
------
+------
 
 * #1530: Fix the issue with TypeError being swallowed by
   decorated handlers.
 
 v8.1.2
------
+------
 
 * #1508
 
 v8.1.1
------
+------
 
 * #1497: Handle errors thrown by ``ssl_module: 'builtin'``
   when client opens connection to HTTPS port using HTTP.
@@ -130,7 +130,7 @@ v8.1.1
 * Other miscellaneous fixes.
 
 v8.1.0
------
+------
 
 * #1473: ``HTTPError`` now also works as a context manager.
 
@@ -145,14 +145,14 @@ v8.1.0
   exactly one place.
 
 v8.0.1
------
+------
 
 * #1489 via #1493: Additionally reject anything else that's
   not bytes.
 * #1492: systemd socket activation.
 
 v8.0.0
------
+------
 
 * #1483: Remove Deprecated constructs:
 
@@ -169,8 +169,8 @@ v8.0.0
 * Removed unicode filename from the package, working around
   pip #3894 and setuptools #704.
 
-7.1.0
------
+v7.1.0
+------
 
 # 1458: Implement systemd's socket activation mechanism for
   CherryPy servers, based on work sponsored by Endless Computers.
@@ -180,8 +180,8 @@ v8.0.0
   'on demand' (a little bit like inetd and xinetd
   used to do).
 
-7.0.0
------
+v7.0.0
+------
 
 Removed the long-deprecated backward compatibility for
 legacy config keys in the engine. Use the config for the
@@ -193,14 +193,14 @@ namespaced-plugins instead:
  - reload_files -> autoreload.files
  - deadlock_poll_frequency -> timeout_monitor.frequency
 
-6.2.1
------
+v6.2.1
+------
 
 # 1460: Fix KeyError in Bus.publish when signal handlers
   set in config.
 
-6.2.0
------
+v6.2.0
+------
 
 * #1441: Added tool to automatically convert request
   params based on type annotations (primarily in
@@ -210,32 +210,32 @@ namespaced-plugins instead:
     def resource(self, limit: int):
         assert isinstance(limit, int)
 
-6.1.1
------
+v6.1.1
+------
 
 * Issue #1411: Fix issue where autoreload fails when
   the host interpreter for CherryPy was launched using
   ``python -m``.
 
-6.1.0
------
+v6.1.0
+------
 
 * Combined wsgiserver2 and wsgiserver3 modules into a
   single module, ``cherrypy.wsgiserver``.
 
-6.0.2
------
+v6.0.2
+------
 
 * Issue #1445: Correct additional typos.
 
-6.0.1
------
+v6.0.1
+------
 
 * Issue #1444: Correct typos in ``@cherrypy.expose``
   decorators.
 
-6.0.0
------
+v6.0.0
+------
 
 * Setuptools is now required to build CherryPy. Pure
   distutils installs are no longer supported. This change
@@ -254,8 +254,8 @@ namespaced-plugins instead:
 * ``cherrypy.config`` decorator is now used throughout
   the code internally.
 
-5.6.0
------
+v5.6.0
+------
 
 * ``@cherrypy.expose`` now will also set the exposed
   attribute on a class.
@@ -264,8 +264,8 @@ namespaced-plugins instead:
   the attribute explicitly.
 * Removed test-specific code from tutorials.
 
-5.5.0
------
+v5.5.0
+------
 
 * #1397: Fix for filenames with semicolons and quote
   characters in filenames found in headers.
@@ -277,8 +277,8 @@ namespaced-plugins instead:
 * #1352: Ensure that multipart fields are decoded even
   when cached in a file.
 
-5.4.0
------
+v5.4.0
+------
 
 * ``cherrypy.test.webtest.WebCase`` now honors a
   'WEBTEST_INTERACTIVE' environment variable to disable
@@ -289,23 +289,23 @@ namespaced-plugins instead:
 * #748: Removed ``cherrypy.lib.sessions.PostgresqlSession``.
 * #1432: Fix errors with redirects to Unicode URLs.
 
-5.3.0
------
+v5.3.0
+------
 
 * #1202: Add support for specifying a certificate authority when
   serving SSL using the built-in SSL support.
 * Use ssl.create_default_context when available.
 * #1392: Catch platform-specific socket errors on OS X.
 * #1386: Fix parsing of URIs containing ``://`` in the path part.
 
-5.2.0
------
+v5.2.0
+------
 
 * #1410: Moved hosting to Github (
   `cherrypy/cherrypy <https://github.com/cherrypy/cherrypy>`_.
 
-5.1.0
------
+v5.1.0
+------
 
 * Bugfix issue #1315 for ``test_HTTP11_pipelining`` test in Python 3.5
 * Bugfix issue #1382 regarding the keyword arguments support for Python 3
@@ -322,13 +322,13 @@ namespaced-plugins instead:
   as a daemon on ``cherrypy.process.plugins.SignalHandler`` to allow
   the execution of the testsuite under CI tools.
 
-5.0.1
------
+v5.0.1
+------
 
 * Bugfix for NameError following #94.
 
-5.0.0
------
+v5.0.0
+------
 
 * Removed deprecated support for ``ssl_certificate`` and
   ``ssl_private_key`` attributes and implicit construction
@@ -338,35 +338,35 @@ namespaced-plugins instead:
 * Pull request #94: In proxy tool, defer to Host header for
   resolving the base if no base is supplied.
 
-4.0.0
------
+v4.0.0
+------
 
 * Drop support for Python 2.5 and earlier.
 * No longer build Windows installers by default.
 
-3.8.2
------
+v3.8.2
+------
 
 * Pull Request #116: Correct InternalServerError when null bytes in
   static file path. Now responds with 404 instead.
 
-3.8.0
------
+v3.8.0
+------
 
 * Pull Request #96: Pass ``exc_info`` to logger as keyword rather than
   formatting the error and injecting into the message.
 
-3.7.0
------
+v3.7.0
+------
 
 * CherryPy daemon may now be invoked with ``python -m cherrypy`` in
   addition to the ``cherryd`` script.
 * Issue #1298: Fix SSL handling on CPython 2.7 with builtin SSL module
   and pyOpenSSL 0.14. This change will break PyPy for now.
 * Several documentation fixes.
 
-3.6.0
------
+v3.6.0
+------
 
 * Fixed HTTP range headers for negative length larger than content size.
 * Disabled universal wheel generation as wsgiserver has Python duality.
@@ -378,19 +378,19 @@ namespaced-plugins instead:
 * Issue #1019: Allow logging host name in the access log.
 * Pull Request #50: Fixed race condition in session cleanup.
 
-3.5.0
------
+v3.5.0
+------
 
 * Issue #1301: When the incoming queue is full, now reject additional
   connections. This functionality was added to CherryPy 3.0, but
   unintentionally lost in 3.1.
 
-3.4.0
------
+v3.4.0
+------
 
 * Miscellaneous quality improvements.
 
-3.3.0
------
+v3.3.0
+------
 
 CherryPy adopts semver.

cherrypy/lib/encoding.py

@@ -321,9 +321,9 @@ def gzip(compress_level=5, mime_types=['text/html', 'text/plain'],
     values in the mime_types arg before calling this function.
 
     The provided list of mime-types must be of one of the following form:
-        * type/subtype
-        * type/*
-        * type/*+subtype
+        * `type/subtype`
+        * `type/*`
+        * `type/*+subtype`
 
     No compression is performed if any of the following hold:
         * The client sends no Accept-Encoding request header

cherrypy/lib/httputil.py

@@ -53,7 +53,7 @@ def urljoin(*atoms):
 
 
 def urljoin_bytes(*atoms):
-    """Return the given path *atoms, joined into a single URL.
+    """Return the given path `*atoms`, joined into a single URL.
 
     This will correctly join a SCRIPT_NAME and PATH_INFO into the
     original URL, even if either atom is blank.

docs/conf.py

@@ -39,6 +39,8 @@ def try_import(mod_name):
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
     'rst.linker',
 ]