On Tue, Nov 20, 2012 at 05:43:18PM +0100, Matthias Klose wrote: > Am 20.11.2012 11:02, schrieb Jonathan Ballet: > > In short, is is possible to provide the API documentation of Twisted as > > a package (either as part of twisted-doc or into another package)? > > sure. however you did forget to attach the patch.
Asked so nicely, I couldn't resist to make one. It's my first time patching Debian packaging things, so it might be rough on the edge. I'm not sure, in particular, if the approach is ok. Please find the attached patch to this email. Thanks, Jonathan
diff -ruN debian.orig/control debian/control --- debian.orig/control 2012-05-02 20:11:34.000000000 +0800 +++ debian/control 2012-11-25 18:38:14.000000000 +0800 @@ -3,7 +3,7 @@ Priority: optional Maintainer: Matthias Klose <d...@debian.org> Uploaders: Free Ekanayaka <fr...@debian.org> -Build-Depends: debhelper (>=7.0.50~), python-all-dev (>= 2.6.6-3~), python-all-dbg, python-zope.interface-dbg, patch +Build-Depends: debhelper (>=7.0.50~), python-all-dev (>= 2.6.6-3~), python-all-dbg, python-zope.interface-dbg, patch, python-pydoctor Build-Conflicts: python-setuptools XS-Python-Version: all Standards-Version: 3.9.3 diff -ruN debian.orig/patches/index-doc.diff debian/patches/index-doc.diff --- debian.orig/patches/index-doc.diff 1970-01-01 08:00:00.000000000 +0800 +++ debian/patches/index-doc.diff 2012-11-28 14:36:06.000000000 +0800 @@ -0,0 +1,21 @@ +--- twisted-12.0.0.orig/doc/index.html 2012-11-28 14:28:43.000000000 +0800 ++++ twisted-12.0.0/doc/index.html 2012-11-28 14:31:17.000000000 +0800 +@@ -20,12 +20,13 @@ + <li><a href="development/index.html" shape="rect">Development of Twisted</a>: for people who + want to work on Twisted itself</li> + </ul> +-<p>An <a href="http://twistedmatrix.com/documents/current/api/"; shape="rect">API +- reference</a> is available on the twistedmatrix web site.</p> +- ++<p>An <a href="apidocs/" shape="rect">API reference</a> is also available. ++You can find the ++<a href="http://twistedmatrix.com/documents/current/api/"; shape="rect">latest ++ reference</a> on the twistedmatrix web site.</p> + </div> + + <p><a href="howto/index.html">Index</a></p> + <span class="version">Version: 12.0.0</span> + </body> +-</html> +\ No newline at end of file ++</html> diff -ruN debian.orig/patches/series debian/patches/series --- debian.orig/patches/series 2012-05-02 20:11:34.000000000 +0800 +++ debian/patches/series 2012-11-28 14:33:35.000000000 +0800 @@ -1 +1,2 @@ tap2deb.diff +index-doc.diff diff -ruN debian.orig/rules debian/rules --- debian.orig/rules 2012-05-02 20:11:34.000000000 +0800 +++ debian/rules 2012-11-28 15:25:30.000000000 +0800 @@ -10,7 +10,7 @@ gamesdir = debian/twisted-quotes/usr/share/games/fortunes -twersion := $(subst twisted-,,$(notdir $(CURDIR))) +twversion := $(subst twisted-,,$(notdir $(CURDIR))) include /usr/share/python/python.mk @@ -24,6 +24,10 @@ python$*-dbg setup.py build touch $@ +build-doc: + -pydoctor --html-write-function-pages --add-package twisted + + clean: rm -rf *-stamp build-python* build rm -rf $(addprefix debian/,$(packages)) debian/files debian/substvars @@ -31,7 +35,7 @@ find . -name "*.pyc" |xargs -r rm dh_clean -install: build-stamp install-prereq $(PYVERS:%=install-python%) install-nover +install: build-doc build-stamp install-prereq $(PYVERS:%=install-python%) install-nover install-prereq: build-stamp dh_testdir @@ -66,8 +70,8 @@ : # python-twisted mkdir -p debian/python-twisted/$(call py_libdir,$*) - sed 's/@twersion@/$(twversion)/' debian/Twisted.egg-info.in \ - > debian/python-twisted/$(call py_libdir,$*)/Twisted-$(twersion).egg-info + sed 's/@twversion@/$(twversion)/' debian/Twisted.egg-info.in \ + > debian/python-twisted/$(call py_libdir,$*)/Twisted-$(twversion).egg-info : # Replace all '#!' calls to python with /usr/bin/python : # and make them executable @@ -92,6 +96,7 @@ : # twisted-doc mkdir -p debian/twisted-doc/usr/share/doc/twisted-doc cp -a doc/* debian/twisted-doc/usr/share/doc/twisted-doc/ + cp -ua apidocs debian/twisted-doc/usr/share/doc/twisted-doc/ -find debian/twisted-doc -type d -name man | xargs rm -rf mkdir -p debian/python-twisted-core/usr/share/man/man1 @@ -99,6 +104,16 @@ cp -p $$i debian/python-twisted-core/usr/share/man/man1/; \ done + # Replace links to Twisted website API doc by links to the local doc. We + # need to compute path to the API which goes up enough in the folder + # hierarchy to access the doc. + for i in $$(cd debian/twisted-doc/usr/share/doc/twisted-doc/ && \ + grep -rl "http://twistedmatrix.com/documents/$(twversion)/api/" .); do \ + path="$$(echo $$i | sed "s:[^/]::g" | sed "s:/:../:g" | cut -c 4-)apidocs/"; \ + sed -i "s:http\://twistedmatrix.com/documents/$(twversion)/api/:$$path:g" \ + debian/twisted-doc/usr/share/doc/twisted-doc/$$i; \ + done + binary-indep: build install dh_testdir dh_testroot
