[PATCH] Automatically build and ship documentation
Build documentation in debian/gem2deb_generated_docs/html, ship it in
/usr/share/doc/$package/html.
* dh_make_ruby: Create debhelper files for dirs, links, doc-base, and docs
to install documentation automatically built by dh_ruby. Add authors
function wrapping metadata.authors.
* dh_ruby: call documentation clean and build functions from installer.
Build documentation by calling rdoc.
* installer: clean and build documentation. Introduce new attribute
docdir and add :docdir to destdir function.
* metadata: add authors attribute.
* gem2deb: add DOC_DIR attribute.
* Add unit and integration tests.
+ Add documentation sample package.
NB! This does not suggest libjs-jquery, but leaves it to the user to
install if they want fancy presentation. This is because libjs-jquery
recommends javascript-common which in turn suggests apache | lighttpd |
httpd, leading to a lot of things automatically installed if suggests
was configured to install automatically.
---
lib/gem2deb.rb | 2 +
lib/gem2deb/dh_make_ruby.rb | 61 +++++++++++++++++-----
lib/gem2deb/dh_ruby.rb | 10 +++-
lib/gem2deb/installer.rb | 17 ++++++
lib/gem2deb/metadata.rb | 8 +++
test/integration/gem2deb_test.rb | 6 +++
test/sample/documentation/CHANGELOG.rdoc | 1 +
test/sample/documentation/debian/changelog | 5 ++
test/sample/documentation/debian/compat | 1 +
test/sample/documentation/debian/control | 18 +++++++
test/sample/documentation/debian/copyright | 35 +++++++++++++
.../documentation/debian/ruby-documentation.dirs | 1 +
.../debian/ruby-documentation.doc-base | 10 ++++
.../documentation/debian/ruby-documentation.docs | 3 ++
.../documentation/debian/ruby-documentation.links | 4 ++
test/sample/documentation/debian/rules | 15 ++++++
test/sample/documentation/debian/source/format | 1 +
test/sample/documentation/debian/watch | 2 +
test/sample/documentation/documentation.gemspec | 17 ++++++
test/sample/documentation/lib/documentation.rb | 3 ++
.../documentation/lib/documentation/version.rb | 3 ++
test/unit/dh_make_ruby_test.rb | 16 ++++++
test/unit/metadata_test.rb | 16 ++++++
23 files changed, 240 insertions(+), 15 deletions(-)
create mode 100644 test/sample/documentation/CHANGELOG.rdoc
create mode 100644 test/sample/documentation/debian/changelog
create mode 100644 test/sample/documentation/debian/compat
create mode 100644 test/sample/documentation/debian/control
create mode 100644 test/sample/documentation/debian/copyright
create mode 100644 test/sample/documentation/debian/ruby-documentation.dirs
create mode 100644 test/sample/documentation/debian/ruby-documentation.doc-base
create mode 100644 test/sample/documentation/debian/ruby-documentation.docs
create mode 100644 test/sample/documentation/debian/ruby-documentation.links
create mode 100755 test/sample/documentation/debian/rules
create mode 100644 test/sample/documentation/debian/source/format
create mode 100644 test/sample/documentation/debian/watch
create mode 100644 test/sample/documentation/documentation.gemspec
create mode 100644 test/sample/documentation/lib/documentation.rb
create mode 100644 test/sample/documentation/lib/documentation/version.rb
diff --git a/lib/gem2deb.rb b/lib/gem2deb.rb
index 5623992..4cd5909 100644
--- a/lib/gem2deb.rb
+++ b/lib/gem2deb.rb
@@ -39,6 +39,8 @@ module Gem2Deb
LIBDIR = File.expand_path(File.dirname(__FILE__))
+ DOC_DIR = 'debian/gem2deb_generated_docs/html'
+
def run(*argv)
puts(_format_cmdline(argv)) if $VERBOSE
system(*argv)
diff --git a/lib/gem2deb/dh_make_ruby.rb b/lib/gem2deb/dh_make_ruby.rb
index 723c752..aa134ea 100644
--- a/lib/gem2deb/dh_make_ruby.rb
+++ b/lib/gem2deb/dh_make_ruby.rb
@@ -110,6 +110,16 @@ module Gem2Deb
[source_package_name, gem_version].join('-')
end
+ def authors
+ if defined? metadata.author
+ [metadata.author]
+ elsif defined? metadata.authors
+ metadata.authors
+ else
+ [""]
+ end
+ end
+
def homepage
metadata.homepage
end
@@ -301,16 +311,43 @@ module Gem2Deb
end
def other_files
- # docs
- docs = ""
- if File::directory?('doc')
- docs += <<-EOF
-# FIXME: doc/ dir found in source. Consider installing the docs.
-# Examples:
-# doc/manual.html
-# doc/site/*
- EOF
+ # dirs
+ File::open("debian/#{source_package_name}.dirs", 'w') do |f|
+ f.puts "usr/share/doc/#{source_package_name}/html"
end
+
+ # links
+ File::open("debian/#{source_package_name}.links", 'w') do |f|
+ f.puts <<-EOF
+# Symlinking to automatically removed jquery.js.
+# If documentation is changed, update path to docs
+# and remove bundled jquery.js in debian/rules.
+usr/share/javascript/jquery/jquery.js usr/share/doc/#{source_package_name}/html/js/jquery.js
+ EOF
+ end
+
+ # doc-base
+ doc_base = <<-EOF
+Document: #{source_package_name}
+Title: Debian #{source_package_name} Manual
+Author: #{authors.join(", ")}
+Abstract: #{short_description}
+ #{long_description}
+Section: Programming/Ruby
+
+Format: HTML
+Index: /usr/share/doc/#{source_package_name}/html/index.html
+Files: /usr/share/doc/#{source_package_name}/html/*
+ EOF
+ File::open("debian/#{source_package_name}.doc-base", 'w') do |f|
+ f.puts doc_base
+ end
+
+ # docs
+ docs = <<-EOF
+# install docs automatically built by gem2deb
+#{DOC_DIR}
+ EOF
readmes = Dir::glob('README*')
docs += <<-EOF
# FIXME: READMEs found
@@ -318,10 +355,8 @@ module Gem2Deb
readmes.each do |r|
docs << "# #{r}\n"
end
- if docs != ""
- File::open("debian/#{source_package_name}.docs", 'w') do |f|
- f.puts docs
- end
+ File::open("debian/#{source_package_name}.docs", 'w') do |f|
+ f.puts docs
end
# examples
diff --git a/lib/gem2deb/dh_ruby.rb b/lib/gem2deb/dh_ruby.rb
index 94570a9..b9c844d 100644
--- a/lib/gem2deb/dh_ruby.rb
+++ b/lib/gem2deb/dh_ruby.rb
@@ -38,6 +38,7 @@ module Gem2Deb
installers.each do |installer|
installer.run_make_clean_on_extensions
+ installer.clean_documentation
end
puts " Leaving dh_ruby --clean" if @verbose
@@ -49,8 +50,13 @@ module Gem2Deb
end
def build
- # puts " Entering dh_ruby --build" if @verbose
- # puts " Leaving dh_ruby --build" if @verbose
+ puts " Entering dh_ruby --build" if @verbose
+
+ installers.each do |installer|
+ installer.build_documentation
+ end
+
+ puts " Leaving dh_ruby --build" if @verbose
end
def test
diff --git a/lib/gem2deb/installer.rb b/lib/gem2deb/installer.rb
index c1bb23a..7e13e07 100644
--- a/lib/gem2deb/installer.rb
+++ b/lib/gem2deb/installer.rb
@@ -25,6 +25,16 @@ module Gem2Deb
@metadata = Gem2Deb::Metadata.new(@root)
end
+ def clean_documentation
+ FileUtils::remove_dir(File::dirname(docdir), force=true)
+ end
+
+ def build_documentation
+ run("rdoc", "--output", docdir, libdir)
+ # remove built jquery.js, .links file symlinks to file in libjs-jquery
+ FileUtils::rm_f(File.join(destdir(:docdir), "js/jquery.js"))
+ end
+
def install_files_and_build_extensions
install_files(bindir, destdir(:bindir), 755) if File::directory?(bindir)
@@ -136,6 +146,10 @@ module Gem2Deb
SUPPORTED_RUBY_VERSIONS.keys
end
+ def docdir
+ @docdir ||= File.join(self.root, DOC_DIR)
+ end
+
def bindir
@bindir ||= File.join(self.root, 'bin')
end
@@ -147,6 +161,7 @@ module Gem2Deb
# This function returns the installation path for the given
# package and the given target, which is one of:
# * :bindir
+ # * :docdir
# * :libdir
# * :archdir
# * :prefix
@@ -160,6 +175,8 @@ module Gem2Deb
return dir
when :bindir
return File.join(dir, BIN_DIR)
+ when :docdir
+ return File.join(dir, "usr/share/doc/#{binary_package}/html")
when :libdir
return File.join(dir, RUBY_CODE_DIR)
when :archdir
diff --git a/lib/gem2deb/metadata.rb b/lib/gem2deb/metadata.rb
index fa1f8b2..2b483e0 100644
--- a/lib/gem2deb/metadata.rb
+++ b/lib/gem2deb/metadata.rb
@@ -58,6 +58,14 @@ module Gem2Deb
@version ||= gemspec && gemspec.version.to_s || read_version_from(source_dir) || '0.1.0~FIXME'
end
+ def author
+ gemspec && gemspec.author
+ end
+
+ def authors
+ gemspec && gemspec.authors
+ end
+
def homepage
gemspec && gemspec.homepage
end
diff --git a/test/integration/gem2deb_test.rb b/test/integration/gem2deb_test.rb
index 3e3d47b..dfcbcf8 100644
--- a/test/integration/gem2deb_test.rb
+++ b/test/integration/gem2deb_test.rb
@@ -37,6 +37,12 @@ class Gem2DebTest < Gem2DebTestCase
end
end
+ self.build_tree('test/sample/documentation') do |dir|
+ should 'contain generated documentation' do
+ assert_file_exists "#{dir}/debian/gem2deb_generated_docs/html"
+ end
+ end
+
self.build_tree('test/sample/examples') do |dir|
should 'not compress *.rb files installed as examples' do
diff --git a/test/sample/documentation/CHANGELOG.rdoc b/test/sample/documentation/CHANGELOG.rdoc
new file mode 100644
index 0000000..5bb306c
--- /dev/null
+++ b/test/sample/documentation/CHANGELOG.rdoc
@@ -0,0 +1 @@
+upstream changelog here
diff --git a/test/sample/documentation/debian/changelog b/test/sample/documentation/debian/changelog
new file mode 100644
index 0000000..2fbf0c3
--- /dev/null
+++ b/test/sample/documentation/debian/changelog
@@ -0,0 +1,5 @@
+ruby-documentation (0.0.1-1) UNRELEASED; urgency=low
+
+ * Initial release (Closes: #nnnn)
+
+ -- Per Andersson <avtobiff@debian.org> Fri, 18 Apr 2014 22:55:36 +0200
diff --git a/test/sample/documentation/debian/compat b/test/sample/documentation/debian/compat
new file mode 100644
index 0000000..7f8f011
--- /dev/null
+++ b/test/sample/documentation/debian/compat
@@ -0,0 +1 @@
+7
diff --git a/test/sample/documentation/debian/control b/test/sample/documentation/debian/control
new file mode 100644
index 0000000..3f45801
--- /dev/null
+++ b/test/sample/documentation/debian/control
@@ -0,0 +1,18 @@
+Source: ruby-documentation
+Section: ruby
+Priority: optional
+Maintainer: Debian Ruby Extras Maintainers <pkg-ruby-extras-maintainers@lists.alioth.debian.org>
+Uploaders: Per Andersson <avtobiff@debian.org>
+Build-Depends: debhelper (>= 7.0.50~), gem2deb (>= 0.7.5~)
+Standards-Version: 3.9.5
+#Vcs-Git: git://anonscm.debian.org/pkg-ruby-extras/ruby-documentation.git
+#Vcs-Browser: http://anonscm.debian.org/gitweb/?p=pkg-ruby-extras/ruby-documentation.git;a=summary
+Homepage: http://wiki.debian.org/Teams/Ruby
+XS-Ruby-Versions: all
+
+Package: ruby-documentation
+Architecture: all
+XB-Ruby-Versions: ${ruby:Versions}
+Depends: ${shlibs:Depends}, ${misc:Depends}, ruby | ruby-interpreter
+Description: Documentation test
+ A simple test to check documentation generation.
diff --git a/test/sample/documentation/debian/copyright b/test/sample/documentation/debian/copyright
new file mode 100644
index 0000000..91b4de8
--- /dev/null
+++ b/test/sample/documentation/debian/copyright
@@ -0,0 +1,35 @@
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: documentation
+Source: FIXME <http://example.com/>
+
+Files: *
+Copyright: <years> <put author's name and email here>
+ <years> <likewise for another author>
+License: GPL-2+ (FIXME)
+
+Files: debian/*
+Copyright: 2014 Per Andersson <avtobiff@debian.org>
+License: GPL-2+ (FIXME)
+Comment: the Debian packaging is licensed under the same terms as the original package.
+
+License: GPL-2+ (FIXME)
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ .
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE. See the GNU General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU General Public
+ License along with this package; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA 02110-1301 USA
+ .
+ On Debian systems, the full text of the GNU General Public
+ License version 2 can be found in the file
+ `/usr/share/common-licenses/GPL-2'.
diff --git a/test/sample/documentation/debian/ruby-documentation.dirs b/test/sample/documentation/debian/ruby-documentation.dirs
new file mode 100644
index 0000000..cd667f7
--- /dev/null
+++ b/test/sample/documentation/debian/ruby-documentation.dirs
@@ -0,0 +1 @@
+usr/share/doc/ruby-documentation/html
diff --git a/test/sample/documentation/debian/ruby-documentation.doc-base b/test/sample/documentation/debian/ruby-documentation.doc-base
new file mode 100644
index 0000000..da0e9de
--- /dev/null
+++ b/test/sample/documentation/debian/ruby-documentation.doc-base
@@ -0,0 +1,10 @@
+Document: ruby-documentation
+Title: Debian ruby-documentation Manual
+Author: Debian Ruby Team
+Abstract: Documentation test
+ A simple test to check documentation generation.
+Section: Programming/Ruby
+
+Format: HTML
+Index: /usr/share/doc/ruby-documentation/html/index.html
+Files: /usr/share/doc/ruby-documentation/html/*
diff --git a/test/sample/documentation/debian/ruby-documentation.docs b/test/sample/documentation/debian/ruby-documentation.docs
new file mode 100644
index 0000000..b1b94d6
--- /dev/null
+++ b/test/sample/documentation/debian/ruby-documentation.docs
@@ -0,0 +1,3 @@
+# install docs automatically built by gem2deb
+debian/gem2deb_generated_docs/html
+# FIXME: READMEs found
diff --git a/test/sample/documentation/debian/ruby-documentation.links b/test/sample/documentation/debian/ruby-documentation.links
new file mode 100644
index 0000000..0a68777
--- /dev/null
+++ b/test/sample/documentation/debian/ruby-documentation.links
@@ -0,0 +1,4 @@
+# Symlinking to automatically removed jquery.js.
+# If documentation is changed, update path to docs
+# and remove bundled jquery.js in debian/rules.
+usr/share/javascript/jquery/jquery.js usr/share/doc/ruby-documentation/html/js/jquery.js
diff --git a/test/sample/documentation/debian/rules b/test/sample/documentation/debian/rules
new file mode 100755
index 0000000..06981cd
--- /dev/null
+++ b/test/sample/documentation/debian/rules
@@ -0,0 +1,15 @@
+#!/usr/bin/make -f
+#export DH_VERBOSE=1
+#
+# Uncomment to ignore all test failures (but the tests will run anyway)
+#export DH_RUBY_IGNORE_TESTS=all
+#
+# Uncomment to ignore some test failures (but the tests will run anyway).
+# Valid values:
+#export DH_RUBY_IGNORE_TESTS=ruby2.0 ruby2.1 require-rubygems
+#
+# If you need to specify the .gemspec (eg there is more than one)
+#export DH_RUBY_GEMSPEC=gem.gemspec
+
+%:
+ dh $@ --buildsystem=ruby --with ruby
diff --git a/test/sample/documentation/debian/source/format b/test/sample/documentation/debian/source/format
new file mode 100644
index 0000000..163aaf8
--- /dev/null
+++ b/test/sample/documentation/debian/source/format
@@ -0,0 +1 @@
+3.0 (quilt)
diff --git a/test/sample/documentation/debian/watch b/test/sample/documentation/debian/watch
new file mode 100644
index 0000000..08caa70
--- /dev/null
+++ b/test/sample/documentation/debian/watch
@@ -0,0 +1,2 @@
+version=3
+http://pkg-ruby-extras.alioth.debian.org/cgi-bin/gemwatch/documentation .*/documentation-(.*).tar.gz
diff --git a/test/sample/documentation/documentation.gemspec b/test/sample/documentation/documentation.gemspec
new file mode 100644
index 0000000..25dec1c
--- /dev/null
+++ b/test/sample/documentation/documentation.gemspec
@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+$:.unshift 'lib'
+require 'documentation/version'
+
+spec = Gem::Specification.new do |s|
+ s.name = "documentation"
+ s.version = Documentation::VERSION
+ s.author = "Debian Ruby Team"
+ s.email = "pkg-ruby-extras-maintainers@lists.alioth.debian.org"
+ s.homepage = "http://wiki.debian.org/Teams/Ruby";
+ s.platform = Gem::Platform::RUBY
+ s.summary = "Documentation test"
+ s.files = ["documentation.gemspec", "lib/documentation.rb",
+ "lib/documentation/version.rb"]
+ s.require_path = "lib"
+ s.description = "A simple test to check documentation generation."
+end
diff --git a/test/sample/documentation/lib/documentation.rb b/test/sample/documentation/lib/documentation.rb
new file mode 100644
index 0000000..569792f
--- /dev/null
+++ b/test/sample/documentation/lib/documentation.rb
@@ -0,0 +1,3 @@
+module Documentation
+ # Your code goes here
+end
diff --git a/test/sample/documentation/lib/documentation/version.rb b/test/sample/documentation/lib/documentation/version.rb
new file mode 100644
index 0000000..3f406d5
--- /dev/null
+++ b/test/sample/documentation/lib/documentation/version.rb
@@ -0,0 +1,3 @@
+module Documentation
+ VERSION = "0.0.1"
+end
diff --git a/test/unit/dh_make_ruby_test.rb b/test/unit/dh_make_ruby_test.rb
index 688aeb6..ab9ddf6 100644
--- a/test/unit/dh_make_ruby_test.rb
+++ b/test/unit/dh_make_ruby_test.rb
@@ -39,6 +39,10 @@ class DhMakeRubyTest < Gem2DebTestCase
debian/compat
debian/watch
debian/source/format
+ debian/ruby-simplegem.dirs
+ debian/ruby-simplegem.doc-base
+ debian/ruby-simplegem.docs
+ debian/ruby-simplegem.links
].each do |file|
filename = File.join(DEBIANIZED_SIMPLE_GEM, file)
should "create #{file}" do
@@ -92,6 +96,18 @@ class DhMakeRubyTest < Gem2DebTestCase
should 'create debian/rules' do
assert_file_exists File.join(TEST_SIMPLE_GIT, 'debian/rules')
end
+ should 'create debian/ruby-simplegit.dirs' do
+ assert_file_exists File.join(TEST_SIMPLE_GIT, 'debian/ruby-simplegit.dirs')
+ end
+ should 'create debian/ruby-simplegit.doc-base' do
+ assert_file_exists File.join(TEST_SIMPLE_GIT, 'debian/ruby-simplegit.doc-base')
+ end
+ should 'create debian/ruby-simplegit.docs' do
+ assert_file_exists File.join(TEST_SIMPLE_GIT, 'debian/ruby-simplegit.docs')
+ end
+ should 'create debian/ruby-simplegit.links' do
+ assert_file_exists File.join(TEST_SIMPLE_GIT, 'debian/ruby-simplegit.links')
+ end
end
FANCY_PACKAGE_TARBALL = File.join(tmpdir, 'fancy-package-0.0.1.tar.gz')
diff --git a/test/unit/metadata_test.rb b/test/unit/metadata_test.rb
index cbc72f0..aeb1d63 100644
--- a/test/unit/metadata_test.rb
+++ b/test/unit/metadata_test.rb
@@ -29,6 +29,12 @@ class MetaDataTest < Gem2DebTestCase
setup do
@metadata = Gem2Deb::Metadata.new('test/tmp')
end
+ should 'have no author' do
+ assert_nil @metadata.author
+ end
+ should 'have no authors' do
+ assert_nil @metadata.authors
+ end
should 'have no homepage' do
assert_nil @metadata.homepage
end
@@ -74,6 +80,16 @@ class MetaDataTest < Gem2DebTestCase
assert_equal '0.0.1', @metadata.version
end
+ should 'obtain author from gemspec' do
+ @gemspec.stubs(:author).returns('Debian Ruby Team')
+ assert_equal 'Debian Ruby Team', @metadata.author
+ end
+
+ should 'obtain authors from gemspec' do
+ @gemspec.stubs(:authors).returns(['Debian Ruby Team', 'Another Author'])
+ assert_equal ['Debian Ruby Team', 'Another Author'], @metadata.authors
+ end
+
should 'obtain homepage from gemspec' do
@gemspec.stubs(:homepage).returns('http://www.debian.org/')
assert_equal 'http://www.debian.org/', @metadata.homepage
--
1.9.2
Reply to: