Re: [PATCH] Automatically build and ship documentation
Bump!
No takers on reviewing this?
Some rework is needed with libjs-jquery recommends (which
Ruby >= 2.0 already does) etc.
--
Per
On Sat, Apr 19, 2014 at 1:02 AM, Per Andersson <avtobiff@gmail.com> wrote:
> 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: