Add Makefile target maintainer-update-website to update d.fd.o/doc/dbus-python

(to use this target, configure your fd.o username, if not the same as
your local username, in ~/.ssh/config).
Move API_CHANGES.txt, HACKING.txt to doc/ directory.
Tweak documentation generation so deprecated stuff isn't documented.

5 files changed, 64 insertions, 27 deletions

diff --git a/Makefile.am b/Makefile.am
index e904bf1..8ca34f2 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -34,12 +34,20 @@ ChangeLog: always-rebuild
 		fi; \
 	fi
 
-TXT_RSTDOCS = doc/tutorial.txt API_CHANGES.txt HACKING.txt
+TXT_RSTDOCS = doc/tutorial.txt doc/API_CHANGES.txt doc/HACKING.txt
 RSTDOCS = README NEWS TODO
 dist_doc_DATA = $(TXT_RSTDOCS) $(RSTDOCS)
 
+maintainer-update-website: _maintainer-update-apidocs \
+	_maintainer-update-htmldocs
+
 if ENABLE_DOCS
-HTML_TXT_RSTDOCS = doc/tutorial.html API_CHANGES.html HACKING.html
+_maintainer-update-htmldocs: $(HTML_TXT_RSTDOCS) $(HTML_RSTDOCS)
+	rsync -rtvzPp --chmod=Dg+s,ug+rwX,o=rX doc \
+	$(RSTDOCS) $(HTML_RSTDOCS) \
+	dbus.freedesktop.org:/srv/dbus.freedesktop.org/www/doc/dbus-python/
+
+HTML_TXT_RSTDOCS = doc/tutorial.html doc/API_CHANGES.html doc/HACKING.html
 HTML_RSTDOCS = README.html NEWS.html TODO.html
 nodist_doc_DATA = $(HTML_TXT_RSTDOCS) $(HTML_RSTDOCS)
 
@@ -49,6 +57,11 @@ $(HTML_TXT_RSTDOCS) : %.html: %.txt
 		$(RST2HTML) $(RST2HTMLFLAGS) $< $@
 $(HTML_RSTDOCS) : %.html: %
 		$(RST2HTML) $(RST2HTMLFLAGS) $< $@
+else
+_maintainer-update-htmldocs:
+	@echo "*** Not updating the HTML docs on the website - install rst2html"
+	@echo "*** from http://docutils.sourceforge.net/ and configure with "
+	@echo "*** --enable-html-docs"
 endif
 
 if ENABLE_API_DOCS
@@ -72,12 +85,22 @@ api api/index.html: $(python_PYTHON) dbus/.doc-needs-rebuild-stamp \
 		    _dbus_glib_bindings/_dbus_glib_bindings.la
 	rm -rf api
 	mkdir api
-	PYTHONPATH=$(APIDOC_PYTHONPATH) $(EPYDOC) -o api --html \
+	PYTHONPATH=$(APIDOC_PYTHONPATH) DBUS_PYTHON_NO_DEPRECATED=1 $(PYTHON) -Wignore::DeprecationWarning $(EPYDOC) -o api --html \
 		--docformat restructuredtext -v \
-		`find dbus -name '*.py' \
+		`find dbus -name '*.py' | grep -v dbus_bindings \
 			| sed -e 's#/__init__\.py##g' \
 				-e 's/\.py\>//g' -e 's#/#.#'g` \
-	|| { rm -rf api; exit 1; }
+		|| { rm -rf api; exit 1; }
+
+_maintainer-update-apidocs: api
+	rsync -rtvzPp --chmod=Dg+s,ug+rwX,o=rX api/ \
+	dbus.freedesktop.org:/srv/dbus.freedesktop.org/www/doc/dbus-python/api/
+else
+_maintainer-update-apidocs:
+	@echo "*** Not updating the API docs on the website - install epydoc 3"
+	@echo "*** alpha (or newer) and configure with --enable-api-docs"
 endif
 
-.PHONY: cross-test-compile cross-test-server cross-test-client always-rebuild
+.PHONY: cross-test-compile cross-test-server cross-test-client \
+	always-rebuild maintainer-update-website \
+	_maintainer-update-apidocs _maintainer-update-htmldocs
diff --git a/dbus/__init__.py b/dbus/__init__.py
index 185e0d8..81246dc 100644
--- a/dbus/__init__.py
+++ b/dbus/__init__.py
@@ -143,6 +143,8 @@ See `dbus.service.Object`.
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
+import os
+
 __all__ = (
            # from _dbus
            'Bus', 'SystemBus', 'SessionBus', 'StarterBus',
@@ -196,4 +198,7 @@ from _dbus_bindings import ObjectPath, ByteArray, Signature, Byte, Boolean,\
                            Double, String, Array, Struct, Dictionary, \
                            UTF8String
 from dbus._dbus import Bus, SystemBus, SessionBus, StarterBus, Interface
-from dbus._dbus import dbus_bindings    # for backwards compat
+
+
+if 'DBUS_PYTHON_NO_DEPRECATED' not in os.environ:
+    from dbus._dbus import dbus_bindings    # for backwards compat
diff --git a/dbus/_dbus.py b/dbus/_dbus.py
index 40b73d3..d0f2f1b 100644
--- a/dbus/_dbus.py
+++ b/dbus/_dbus.py
@@ -33,6 +33,7 @@ UTF8String = _dbus_bindings.UTF8String
 DBusException = _dbus_bindings.DBusException
 BusImplementation = _dbus_bindings.BusImplementation
 
+import os
 import logging
 import weakref
 
@@ -835,21 +836,23 @@ If you need additional public API, please contact the maintainers via
 <dbus@lists.freedesktop.org>.
 """)
 
-class _DBusBindingsEmulation:
-    """A partial emulation of the dbus_bindings module."""
-    _module = None
-    def __str__(self):
-        return '_DBusBindingsEmulation()'
-    def __repr__(self):
-        return '_DBusBindingsEmulation()'
-    def __getattr__(self, attr):
-        if self._module is None:
-            from warnings import warn as _warn
-            _warn(_dbus_bindings_warning, DeprecationWarning, stacklevel=2)
-
-            import dbus.dbus_bindings as m
-            self._module = m
-        return getattr(self._module, attr)
-
-dbus_bindings = _DBusBindingsEmulation()
-"""Deprecated, don't use."""
+if 'DBUS_PYTHON_NO_DEPRECATED' not in os.environ:
+
+    class _DBusBindingsEmulation:
+        """A partial emulation of the dbus_bindings module."""
+        _module = None
+        def __str__(self):
+            return '_DBusBindingsEmulation()'
+        def __repr__(self):
+            return '_DBusBindingsEmulation()'
+        def __getattr__(self, attr):
+            if self._module is None:
+                from warnings import warn as _warn
+                _warn(_dbus_bindings_warning, DeprecationWarning, stacklevel=2)
+
+                import dbus.dbus_bindings as m
+                self._module = m
+            return getattr(self._module, attr)
+
+    dbus_bindings = _DBusBindingsEmulation()
+    """Deprecated, don't use."""
diff --git a/API_CHANGES.txt b/doc/API_CHANGES.txt
index ace4f5b..ace4f5b 100644
--- a/API_CHANGES.txt
+++ b/doc/API_CHANGES.txt
diff --git a/HACKING.txt b/doc/HACKING.txt
index 16bbffd..0811156 100644
--- a/HACKING.txt
+++ b/doc/HACKING.txt
@@ -3,7 +3,7 @@ D-Bus Python bindings - notes for hackers
 =========================================
 
 :Author: Simon McVittie, `Collabora`_
-:Date: 2006-12-18
+:Date: 2007-01-24
 
 .. _Collabora: http://www.collabora.co.uk/
 
@@ -30,7 +30,7 @@ Modules
 ``dbus.mainloop.glib`` is the public API for the GLib main loop integration.
 
 ``dbus.types`` and ``dbus.exceptions`` are mainly for backwards
-compatibility - use ``dbus`` instead in new code.
+compatibility - use ``dbus`` instead in new code. Ditto ``dbus.glib``.
 
 ``dbus._dbus``, ``dbus.introspect_parser``, ``dbus.proxies`` are internal
 implementation details.
@@ -50,6 +50,12 @@ as well as the usual "be nice to other threads", D-Bus does its own
 locking and we don't want to deadlock with it. Most Connection methods
 can block.
 
+Other notes
+===========
+
+Code needs to be Python 2.5 compatible - use Py_ssize_t where appropriate.
+See http://www.python.org/dev/peps/pep-0353/ for details.
+
 Indentation and other holy wars
 ===============================