Merge pull request #5 from zopefoundation/api-docs

Publish docs on RTD

.gitignore

@@ -5,3 +5,4 @@
 coverage.xml
 docs/_build
 htmlcov/
+.coverage.*

CHANGES.rst

@@ -1,28 +1,29 @@
-Changes
-=======
+=========
+ Changes
+=========
 
-4.4 (unreleased)
-----------------
+4.4.0 (unreleased)
+==================
 
-- Nothing changed yet.
+- Host documentation at https://zopeauthentication.readthedocs.io
 
 
-4.3 (2017-05-11)
-----------------
+4.3.0 (2017-05-11)
+==================
 
 - Add support for Python 3.5 and 3.6.
 
 - Drop support for Python 2.6 and 3.2.
 
 
 4.2.1 (2015-06-05)
-------------------
+==================
 
 - Add support for PyPy3 and Python 3.2.
 
 
 4.2.0 (2014-12-26)
-------------------
+==================
 
 - Add support for PyPy.  PyPy3 support is blocked on a release of a fix for:
   https://bitbucket.org/pypy/pypy/issue/1946
@@ -33,15 +34,15 @@ Changes
 
 
 4.1.0 (2013-02-21)
-------------------
+==================
 
 - Add support for Python 3.3.
 
 - Add ``tox.ini`` and ``MANIFEST.in``.
 
 
 4.0.0 (2012-07-04)
-------------------
+==================
 
 - Break inappropriate testing dependency on ``zope.component.nextutility``.
 
@@ -57,12 +58,12 @@ Changes
 
 
 3.7.1 (2010-04-30)
-------------------
+==================
 
 - Remove undeclared testing dependency on ``zope.testing``.
 
 3.7.0 (2009-03-14)
-------------------
+==================
 
 Initial release. This package was split off from ``zope.app.security`` to
 provide a separate common interface definition for authentication utilities

README.rst

@@ -1,8 +1,30 @@
-``zope.authentication`` README
-==============================
+================================
+ ``zope.authentication`` README
+================================
+
+.. image:: https://img.shields.io/pypi/v/zope.authentication.svg
+        :target: https://pypi.python.org/pypi/zope.authentication/
+        :alt: Latest release
+
+.. image:: https://img.shields.io/pypi/pyversions/zope.authentication.svg
+        :target: https://pypi.org/project/zope.authentication/
+        :alt: Supported Python versions
 
 .. image:: https://travis-ci.org/zopefoundation/zope.authentication.png?branch=master
         :target: https://travis-ci.org/zopefoundation/zope.authentication
 
+.. image:: https://coveralls.io/repos/github/zopefoundation/zope.authentication/badge.svg?branch=master
+        :target: https://coveralls.io/github/zopefoundation/zope.authentication?branch=master
+
+.. image:: https://readthedocs.org/projects/zopeauthentication/badge/?version=latest
+        :target: https://zopeauthentication.readthedocs.io/en/latest/
+        :alt: Documentation Status
+
 This package provides a definition of authentication concepts for use in
-Zope Framework.
+Zope Framework. This includes:
+
+- ``IAuthentication``
+- ``IUnauthenticatedPrincipal``
+- ``ILogout``
+
+Documentation is hosted at https://zopeauthentication.readthedocs.io/en/latest/

docs-requirements.txt

@@ -0,0 +1 @@
+repoze.sphinx.autointerface

docs/api.rst

@@ -0,0 +1,23 @@
+===============
+ API Reference
+===============
+
+Interfaces
+==========
+
+.. automodule:: zope.authentication.interfaces
+
+Principals
+==========
+
+.. automodule:: zope.authentication.principal
+
+Login
+=====
+
+.. automodule:: zope.authentication.loginpassword
+
+Logout
+======
+
+.. automodule:: zope.authentication.logout

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -15,6 +15,10 @@
 
 import sys
 import os
+import pkg_resources
+sys.path.append(os.path.abspath('../src'))
+rqmt = pkg_resources.require('zope.authentication')[0]
+
 
 # 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
@@ -34,6 +38,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
+    'repoze.sphinx.autointerface',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,9 +62,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '4.1'
+version = '%s.%s' % tuple(map(int, rqmt.version.split('.')[:2]))
 # The full version, including alpha/beta/rc tags.
-release = '4.1'
+release = rqmt.version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -265,4 +270,31 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    'http://docs.python.org/': None,
+    'https://zopesecurity.readthedocs.io/en/latest/': None,
+    'https://zopeschema.readthedocs.io/en/latest/': None,
+    'https://zopebrowser.readthedocs.io/en/latest/': None,
+}
+
+extlinks = {'issue': ('https://github.com/zopefoundation/zope.authentication/issues/%s',
+                      'issue #'),
+            'pr': ('https://github.com/zopefoundation/zope.authentication/pull/%s',
+                   'pull request #')}
+
+autodoc_default_flags = [
+    'members',
+    'special-members',
+    'show-inheritance',
+]
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'
+
+def maybe_skip_member(app, what, name, obj, skip, options):
+    if name in ('__dict__', '__component_adapts__',
+                '__implemented__', '__provides__', '__providedBy__',
+                '__weakref__', '__module__',):
+        return True
+
+def setup(app):
+    app.connect('autodoc-skip-member', maybe_skip_member)

docs/index.rst

@@ -1,5 +1,4 @@
-:mod:`zope.authentication`
-==========================
+.. include:: ../README.rst
 
 Contents:
 
@@ -8,13 +7,29 @@ Contents:
 
    logout
    principalterms
+   api
+   changelog
 
+Development
+===========
 
+zope.authentication is hosted at GitHub:
 
+    https://github.com/zopefoundation/zope.authentication/
+
+
+
+Project URLs
+============
+
+* https://pypi.python.org/pypi/zope.authentication       (PyPI entry and downloads)
+
+
+
+==================
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/logout.rst

@@ -7,7 +7,7 @@ Logout Support
    setUp()
 
 Logout support is defined by a simple interface
-:class:`zope.authentication.interfacesILogout`:
+:class:`zope.authentication.interfaces.ILogout`:
 
 .. doctest::
 
@@ -16,9 +16,9 @@ Logout support is defined by a simple interface
 that has a single 'logout' method.
 
 The current use of ILogout is to adapt an
-:class:`from zope.authentication.interfaces.IAuthentication` instance to
-``ILogout``.  To illustrate, we'll create a simple logout implementation that
-adapts ``IAuthentication``:
+:class:`zope.authentication.interfaces.IAuthentication` instance to
+:class:`~.ILogout`.  To illustrate, we'll create a simple logout implementation that
+adapts :class:`~.IAuthentication`:
 
 .. doctest::
 
@@ -47,7 +47,7 @@ and something to represent an authentication utility:
 
    >>> auth = Authentication()
 
-To perform a logout, we adapt auth to ILogout and call 'logout':
+To perform a logout, we adapt auth to ``ILogout`` and call 'logout':
 
 .. doctest::
 

setup.py

@@ -37,6 +37,10 @@ def alltests():
     suites = list(zope.testrunner.find.find_suites(options))
     return unittest.TestSuite(suites)
 
+TESTS_REQUIRE = [
+    'zope.testing',
+    'zope.testrunner',
+]
 
 setup(name='zope.authentication',
       version='4.4.dev0',
@@ -67,28 +71,30 @@ def alltests():
           'Natural Language :: English',
           'Operating System :: OS Independent',
           'Topic :: Internet :: WWW/HTTP',
-          'Framework :: Zope3'],
-      url='http://pypi.python.org/pypi/zope.authentication',
+          'Framework :: Zope3',
+      ],
+      url='https://zopeauthentication.readthedocs.io/',
       license='ZPL 2.1',
       packages=find_packages('src'),
       package_dir={'': 'src'},
       namespace_packages=['zope'],
-      extras_require=dict(
-          test=[
-              'zope.testing',
-          ]),
-      install_requires=['setuptools',
-                        'zope.browser',
-                        'zope.component>=3.6.0',
-                        'zope.i18nmessageid',
-                        'zope.interface',
-                        'zope.schema',
-                        'zope.security',
-                        ],
-      tests_require=[
-          'zope.testing',
-          'zope.testrunner',
+      extras_require={
+          'test': TESTS_REQUIRE,
+          'docs': {
+              'Sphinx',
+              'repoze.sphinx.autointerface',
+          },
+      },
+      install_requires=[
+          'setuptools',
+          'zope.browser',
+          'zope.component>=3.6.0',
+          'zope.i18nmessageid',
+          'zope.interface',
+          'zope.schema',
+          'zope.security',
       ],
+      tests_require=TESTS_REQUIRE,
       test_suite='__main__.alltests',
       include_package_data=True,
       zip_safe=False,