Polish docs a bit

CONTRIBUTING.rst

@@ -0,0 +1,8 @@
+How to Contribute
+=================
+
+Head over to: https://github.com/twisted/ldaptor and submit your bugs or feature requests.
+If you wish to contribute code, just fork it, make a branch and send us a pull request.
+We'll review it, and push back if necessary.
+
+Ldaptor generally follows the coding and documentation standards of the Twisted project.

docs/source/AUTHORS.rst

@@ -1,21 +1,17 @@
+=============
 Contributions
 =============
 
-How to contribute
------------------
-
-Head over to: https://github.com/twisted/ldaptor and submit your bugs or feature requests. If you
-wish to contribute code, just fork it, make a branch and send us a pull request. We'll review it,
-and push back if necessary.
+.. include:: ../../CONTRIBUTING.rst
 
 Contributors
-------------
+============
 
-* Anton Gyllenberg
-* Bret Curtis
-* David Strauss
-* HawkOwl
-* Hynek Schlawack
-* Kenny MacDermid
-* Stefan Andersson
-* Tommi Virtanen
+- Anton Gyllenberg
+- Bret Curtis
+- David Strauss
+- HawkOwl
+- Hynek Schlawack
+- Kenny MacDermid
+- Stefan Andersson
+- Tommi Virtanen

docs/source/NEWS.rst

@@ -10,49 +10,53 @@ Ldaptor has a new version schema. As a first-party library we now follow Twisted
 License
 ^^^^^^^
 
-    - Ldaptor's original author `Tommi Virtanen <https://github.com/tv42>`_ changed the license to the MIT (Expat) license.
-    - ldaptor.md4 has been replaced by a 3-clause BSD version.
+- Ldaptor's original author `Tommi Virtanen <https://github.com/tv42>`_ changed the license to the MIT (Expat) license.
+- ldaptor.md4 has been replaced by a 3-clause BSD version.
 
 API Changes
 ^^^^^^^^^^^
 
-    - Ldaptor client and server: None
-    - Everything having to do with webui and Nevow have been *removed*.
+- Ldaptor client and server: None
+- Everything having to do with webui and Nevow have been *removed*.
 
 Features
 ^^^^^^^^
 
-    - `Travis CI <https://travis-ci.org/twisted/ldaptor/>`_ is now used for continuous integration.
-    - Test coverage is now measured. We're currently at around 75%.
-    - tox is used now to test ldaptor on all combinations of pypy, Python 2.6, Python 2.7 and Twisted versions from 10.0 until 14.0.
-    - A few ordering bugs that were exposed by that and are fixed now.
-    - ldaptor.protocols.pureldap.LDAPExtendedRequest now has additional tests.
-    - The new ldaptor.protocols.pureldap.LDAPAbandonRequest adds support for abandoning requests.
-    - ldaptor.protocols.pureldap.LDAPBindRequest has basic SASL support now. Higher-level APIs like ldapclient don't expose it yet though.
+- `Travis CI <https://travis-ci.org/twisted/ldaptor/>`_ is now used for continuous integration.
+- Test coverage is now measured. We're currently at around 75%.
+- tox is used now to test ldaptor on all combinations of pypy, Python 2.6, Python 2.7 and Twisted versions from 10.0 until 14.0.
+- A few ordering bugs that were exposed by that and are fixed now.
+- ldaptor.protocols.pureldap.LDAPExtendedRequest now has additional tests.
+- The new ldaptor.protocols.pureldap.LDAPAbandonRequest adds support for abandoning requests.
+- ldaptor.protocols.pureldap.LDAPBindRequest has basic SASL support now.
+  Higher-level APIs like ldapclient don't expose it yet though.
 
 Bugfixes
 ^^^^^^^^
 
-    - ldaptor.protocols.ldap.ldapclient's now uses log.msg for it's debug listing instead of the non-Twisted log.debug.
-    - String literal exceptions have been replaced by real Exceptions.
-    - "bin/ldaptor-ldap2passwd --help" now does not throws an exception anymore (`debian bug #526522 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526522>`_).
-    - ldaptor.delta.Modification and ldaptor.protocols.ldap.ldapsyntax.PasswordSetAggregateError that are used for adding contacts now handle unicode arguments properly.
-    - ldaptor.protocols.pureldap.LDAPExtendedRequest's constructor now handles STARTTLS in accordance to `RFC2251 <http://tools.ietf.org/html/rfc2251>`_ so the constructor of ldaptor.protocols.pureldap.LDAPStartTLSRequest doesn't fail anymore.
-    - ldaptor.protocols.ldap.ldapserver.BaseLDAPServer now uses the correct exception module in dataReceived.
-    - ldaptor.protocols.ldap.ldaperrors.LDAPException: "Fix deprecated exception error"
-    - bin/ldaptor-find-server now imports dns from the correct twisted modules.
-    - bin/ldaptor-find-server now only prints SRV records.
-    - ldaptor.protocols.ldap.ldapsyntax.LDAPEntryWithClient now correctly propagates errors on search(). The test suite has been adapted appropriately.
-    - ldaptor.protocols.ldap.ldapconnector.LDAPConnector now supports specifying a local address when connecting to a server.
-    - The new ldaptor.protocols.pureldap.LDAPSearchResultReference now prevents ldaptor from choking on results containing SearchResultReference (usually from Active Directory servers). It is currently only a stub and silently ignored.
-    - hashlib and built-in set() are now used instead of deprecated modules.
+- ldaptor.protocols.ldap.ldapclient's now uses log.msg for it's debug listing instead of the non-Twisted log.debug.
+- String literal exceptions have been replaced by real Exceptions.
+- "bin/ldaptor-ldap2passwd --help" now does not throws an exception anymore (`debian bug #526522 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526522>`_).
+- ldaptor.delta.Modification and ldaptor.protocols.ldap.ldapsyntax.PasswordSetAggregateError that are used for adding contacts now handle unicode arguments properly.
+- ldaptor.protocols.pureldap.LDAPExtendedRequest's constructor now handles STARTTLS in accordance to `RFC2251 <http://tools.ietf.org/html/rfc2251>`_ so the constructor of ldaptor.protocols.pureldap.LDAPStartTLSRequest doesn't fail anymore.
+- ldaptor.protocols.ldap.ldapserver.BaseLDAPServer now uses the correct exception module in dataReceived.
+- ldaptor.protocols.ldap.ldaperrors.LDAPException: "Fix deprecated exception error"
+- bin/ldaptor-find-server now imports dns from the correct twisted modules.
+- bin/ldaptor-find-server now only prints SRV records.
+- ldaptor.protocols.ldap.ldapsyntax.LDAPEntryWithClient now correctly propagates errors on search().
+  The test suite has been adapted appropriately.
+- ldaptor.protocols.ldap.ldapconnector.LDAPConnector now supports specifying a local address when connecting to a server.
+- The new ldaptor.protocols.pureldap.LDAPSearchResultReference now prevents ldaptor from choking on results containing SearchResultReference (usually from Active Directory servers).
+  It is currently only a stub and silently ignored.
+- hashlib and built-in set() are now used instead of deprecated modules.
 
 Improved Documentation
 ^^^^^^^^^^^^^^^^^^^^^^
 
-    - Added, updated and reworked documentation using Sphinx. `Dia <https://wiki.gnome.org/Apps/Dia/>`_ is required for converting diagrams to svg/png, this might change in the future.
-    - Dia is now invoked correctly for diagram generation in a headless environment.
-    - The documentation is now hosted on https://ldaptor.readthedocs.org/.
+- Added, updated and reworked documentation using Sphinx.
+  `Dia <https://wiki.gnome.org/Apps/Dia/>`_ is required for converting diagrams to svg/png, this might change in the future.
+- Dia is now invoked correctly for diagram generation in a headless environment.
+- The documentation is now hosted on https://ldaptor.readthedocs.org/.
 
 Prehistory
 ----------

docs/source/addressbook-example.rst

@@ -38,13 +38,11 @@ Setting up an LDAP server in 5 seconds
 Python, an easy programming language
 
 **Batteries included!**
-    
+
 Python combines remarkable power with very clear syntax.
 
 Runs on many brands of UNIX, on Windows, OS/2, Mac, Amiga, and many other platforms.
 
-    TODO: add more about getting things setup.
-
 The first step
 --------------
 
@@ -91,13 +89,11 @@ Preparing to connect
 Twisted
 -------
 
-Twisted is an event-driven networking framework written in Python and licensed under the MIT \
-(Expat) License.
+Twisted is an event-driven networking framework written in Python and licensed under the MIT (Expat) License.
 
-Twisted supports TCP, UDP, SSL/TLS, multicast, Unix sockets, a large number of protocols \
-(including HTTP, NNTP, SSH, IRC, FTP, and others), and much more.
+Twisted supports TCP, UDP, SSL/TLS, multicast, Unix sockets, a large number of protocols (including HTTP, NNTP, SSH, IRC, FTP, and others), and much more.
 
-Twisted includes many fullblown applications, such as web, SSH, FTP, DNS and news servers.
+Twisted includes many full-blown applications, such as web, SSH, FTP, DNS and news servers.
 
 Connecting
 ----------
@@ -112,11 +108,12 @@ Connecting
 
 Deferreds
 ---------
-* A promise that a function will at some point have a result.
-* You can attach callback functions to a Deferred.
-* Once it gets a result these callbacks will be called.
-* Also allows you to register a callback for an error, with the default behavior of logging the error.
-* Standard way to handle all sorts of blocking or delayed operations.
+
+- A promise that a function will at some point have a result.
+- You can attach callback functions to a Deferred.
+- Once it gets a result these callbacks will be called.
+- Also allows you to register a callback for an error, with the default behavior of logging the error.
+- Standard way to handle all sorts of blocking or delayed operations.
 
 Searching
 ---------
@@ -208,35 +205,29 @@ A lot of similarities with OO programming languages, but some big differences, t
 
 An LDAP entry corresponds with an object.
 
-Whereas object are usually instances of a single class, LDAP entries can "implement" multiple \
-objectClasses.
+Whereas object are usually instances of a single class, LDAP entries can "implement" multiple objectClasses.
 
 All objectClasses can inherit zero, one or many objectClasses, just like programming classes.
 
-All objectClasses have a root class, known as `top`; many object oriented programming languages \
-have a root class, e.g. named `Object`.
+All objectClasses have a root class, known as `top`; many object oriented programming languages have a root class, e.g. named `Object`.
 
-All objectClasses are either `STRUCTURAL` or `AUXILIARY`; entries can only implement \
-one `STRUCTURAL` objectClass.
+All objectClasses are either `STRUCTURAL` or `AUXILIARY`; entries can only implement one `STRUCTURAL` objectClass.
 
-Lastly, objectClasses of an entry can be changed at will; you only need to take care that the \
-entry has all the `MUST` attribute types, and no attribute types outside of the ones that \
-are `MUST` or `MAY`.
+Lastly, objectClasses of an entry can be changed at will; you only need to take care that the entry has all the `MUST` attribute types, and no attribute types outside of the ones that are `MUST` or `MAY`.
 
 .. NOTE::
     Note that e.g. OpenLDAP doesn't implement this.
 
-Attributes of an entry closely match attributes of objects in programming languages; however, \
- LDAP attributes may have multiple values.
+Attributes of an entry closely match attributes of objects in programming languages; however, LDAP attributes may have multiple values.
 
 Search inputs
 -------------
+
 An example search filter: ``(cn=John Smith)``
 
 A search filter, specifying criteria an entry must fulfill to match.
 
-Scope of the search, either look at the base DN only, only look one level below it, or look at \
-the whole subtree rooted at the base DN.
+Scope of the search, either look at the base DN only, only look one level below it, or look at the whole subtree rooted at the base DN.
 
 Size limit of at most how many matching entries to return.
 
@@ -296,28 +287,34 @@ Our first Python program
 
 Phases of the protocol chat
 ---------------------------
-* Open and bind
-* Search (possibly many times)
-* Unbind and close
+
+- Open and bind
+- Search (possibly many times)
+- Unbind and close
 
 Opening and binding
 -------------------
+
 .. image::  chat-bind.png
 
 Doing a search
 --------------
+
 .. image::  chat-search.png
 
 Doing multiple searches
 -----------------------
+
 .. image::  chat-search-pipeline.png
 
 Unbinding and closing
 ---------------------
+
 .. image::  chat-unbind.png
 
 A complex search filter
 -----------------------
+
 An example::
 
     (&(objectClass=person)
@@ -333,18 +330,19 @@ Object classes
 #. Objectclass defines
     #. What attributetypes an entry MUST have
     #. What attributetypes an entry MAY have
-#. An entry in a phonebook must have a name and a telephone number,
-    and may have a fax number and street address.
+#. An entry in a phonebook must have a name and a telephone number, and may have a fax number and street address.
 
 Schema
 ------
+
 #. A configuration file included in the LDAP server configuration.
 #. A combination of attribute type and object class definitions.
 #. Stored as plain text
 #. Can be requested over an LDAP connection
 
 Attribute type
 --------------
+
 An example::
 
     attributetype ( 2.5.4.4 NAME ( 'sn' 'surname' )
@@ -353,6 +351,7 @@ An example::
 
 
 Can also contain:
+
 #. content data type
 #. comparison and sort mechanism
 #. substring search mechanism
@@ -373,6 +372,7 @@ An example::
 
 Creating schemas
 ----------------
+
 #. Anyone can create their own schema
 #. Need to be globally unique
 #. But try to use already existing ones
@@ -386,5 +386,6 @@ Install Ldaptor: https://github.com/twisted/ldaptor
 
 Learn Python: http://www.python.org/
 
-Learn Twisted. Write a client application for a simple protocol. Read the HOWTOs.
-http://twistedmatrix.com/documents/howto/clients
+Learn Twisted.
+Write a client application for a simple protocol.
+Read the HOWTOs:  http://twistedmatrix.com/documents/current/core/howto/clients.html

docs/source/index.rst

@@ -6,17 +6,18 @@ What is Ldaptor
 
 Ldaptor is a pure-Python Twisted library that implements:
 
-* LDAP client logic
-* separately-accessible LDAP and BER protocol message generation/parsing
-* ASCII-format LDAP filter generation and parsing
-* LDIF format data generation
+- LDAP client logic
+- separately-accessible LDAP and BER protocol message generation/parsing
+- ASCII-format LDAP filter generation and parsing
+- LDIF format data generation
+
+Get it from `PyPI <https://pypi.python.org/pypi/Ldaptor>`_, find out what's new in the :doc:`NEWS`!
 
 Quick Usage Example
 -------------------
 
 .. code-block:: python
 
-    python
     from twisted.internet import reactor, defer
     from ldaptor.protocols.ldap import ldapclient, ldapsyntax, ldapconnector
 
@@ -43,46 +44,29 @@ Quick Usage Example
         reactor.run()
 
 
-User Guide
-----------
-
-.. toctree::
-   :maxdepth: 2
-
-   AUTHORS
-   ldap-intro
+User's Guide
+------------
 
 .. toctree::
    :maxdepth: 1
 
-   NEWS
+   ldap-intro
    addressbook-example
+   ldaptor
 
-Ldaptor API:
-------------
+Meta
+----
 
 .. toctree::
    :maxdepth: 1
 
-   ldaptor
-
-
-Status and History
-==================
-
-Ldaptor was created by Tommi Virtanen (tv42) who developed it during the years 2001-2008.
-From 2007 and onwards mainly bug fixes were added, many contributed by Debian maintainers.
-Development picked back up in 2014 by Bret Curtis (psi29a) with Tommi's consent and was migrated
-to Twisted where it is a first-party Twisted library. Ldaptor can be found here:
-
-`<https://github.com/twisted/ldaptor>`_
-
-The LDAP client library functionality is in active use. It is stable and works very well.
+   NEWS
+   status
+   AUTHORS
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+- :ref:`genindex`
+- :ref:`modindex`
+- :ref:`search`