From 4bed8998b6ce03d01f3cc700881293942a784e6d Mon Sep 17 00:00:00 2001
From: Utkarsh Gupta <utkarsh@debian.org>
Date: Mon, 15 Jun 2020 17:25:30 +0530
Subject: [PATCH] Generate docs/

---
 docs/antora.yml                             |  5 ++
 docs/modules/ROOT/nav.adoc                  |  6 +++
 docs/modules/ROOT/pages/cops.adoc           |  7 +++
 docs/modules/ROOT/pages/cops_packaging.adoc | 59 +++++++++++++++++++++
 docs/modules/ROOT/pages/index.adoc          | 10 ++++
 docs/modules/ROOT/pages/installation.adoc   | 22 ++++++++
 docs/modules/ROOT/pages/usage.adoc          | 42 +++++++++++++++
 7 files changed, 151 insertions(+)
 create mode 100644 docs/antora.yml
 create mode 100644 docs/modules/ROOT/nav.adoc
 create mode 100644 docs/modules/ROOT/pages/cops.adoc
 create mode 100644 docs/modules/ROOT/pages/cops_packaging.adoc
 create mode 100644 docs/modules/ROOT/pages/index.adoc
 create mode 100644 docs/modules/ROOT/pages/installation.adoc
 create mode 100644 docs/modules/ROOT/pages/usage.adoc

diff --git a/docs/antora.yml b/docs/antora.yml
new file mode 100644
index 0000000..54f43bf
--- /dev/null
+++ b/docs/antora.yml
@@ -0,0 +1,5 @@
+name: rubocop-packaging
+title: RuboCop Packaging
+version: master
+nav:
+  - modules/ROOT/nav.adoc
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000..8068090
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,6 @@
+* xref:index.adoc[Home]
+* xref:installation.adoc[Installation]
+* xref:usage.adoc[Usage]
+* xref:cops.adoc[Cops]
+* Cops Documentation
+** xref:cops_packaging.adoc[Packaging]
diff --git a/docs/modules/ROOT/pages/cops.adoc b/docs/modules/ROOT/pages/cops.adoc
new file mode 100644
index 0000000..583e022
--- /dev/null
+++ b/docs/modules/ROOT/pages/cops.adoc
@@ -0,0 +1,7 @@
+// START_COP_LIST
+
+= Department xref:cops_packaging.adoc[Packaging]
+
+* xref:cops_packaging.adoc#packaginggemspecgit[Packaging/GemspecGit]
+
+// END_COP_LIST
diff --git a/docs/modules/ROOT/pages/cops_packaging.adoc b/docs/modules/ROOT/pages/cops_packaging.adoc
new file mode 100644
index 0000000..39e2b75
--- /dev/null
+++ b/docs/modules/ROOT/pages/cops_packaging.adoc
@@ -0,0 +1,59 @@
+= Packaging
+
+== Packaging/GemspecGit
+
+|===
+| Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged
+
+| Enabled
+| Yes
+| No
+| 0.86
+| -
+|===
+
+This cop is used to identify the usage of `git ls-files`
+and suggests to use a plain Ruby alternative, like `Dir`,
+`Dir.glob` or `Rake::FileList` instead.
+
+=== Examples
+
+[source,ruby]
+----
+# bad
+Gem::Specification.new do |spec|
+  spec.files = `git ls-files`.split('\n')
+end
+
+# bad
+Gem::Specification.new do |spec|
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split('\\x0').reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+end
+
+# bad
+Gem::Specification.new do |spec|
+  spec.files         = `git ls-files`.split('\n')
+  spec.test_files    = `git ls-files -- test/{functional,unit}/*`.split('\n')
+  spec.executables   = `git ls-files -- bin/*`.split('\n').map{ |f| File.basename(f) }
+end
+
+# good
+Gem::Specification.new do |spec|
+  spec.files         = Dir['lib/**/*', 'LICENSE', 'README.md']
+  spec.test_files    = Dir['spec/**/*']
+end
+
+# good
+Gem::Specification.new do |spec|
+  spec.files         = Rake::FileList['**/*'].exclude(*File.read('.gitignore').split)
+end
+
+# good
+Gem::Specification.new do |spec|
+  spec.files         = Dir.glob('lib/**/*')
+  spec.test_files    = Dir.glob('test/{functional,test}/*')
+  spec.executables   = Dir.glob('bin/*').map{ |f| File.basename(f) }
+end
+----
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000..925c8a8
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,10 @@
+= RuboCop Packaging
+
+`RuboCop::Packaging` is an extension of [RuboCop](https://rubocop.org/),
+which is a Ruby static code analyzer (a.k.a. linter) and code formatter.
+
+It contains a set of Cops which enforces some of the guidelines that
+are expected of upstream maintainers so that the downstream can build
+their packages in a clean environment without any problems.
+Some of the other basic guidelines can be found
+[here](https://wiki.debian.org/Teams/Ruby/RubyExtras/UpstreamDevelopers).
diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc
new file mode 100644
index 0000000..20d34e6
--- /dev/null
+++ b/docs/modules/ROOT/pages/installation.adoc
@@ -0,0 +1,22 @@
+= Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'rubocop-packaging', require: false
+----
+
+And then execute:
+
+[source,bash]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,bash]
+----
+$ gem install rubocop-packaging
+----
diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc
new file mode 100644
index 0000000..a2d9420
--- /dev/null
+++ b/docs/modules/ROOT/pages/usage.adoc
@@ -0,0 +1,42 @@
+= Usage
+
+You need to tell RuboCop to load the Packaging extension. There are three
+ways to do this:
+
+== RuboCop configuration file
+
+Put this into your `.rubocop.yml` file:
+
+[source,yaml]
+----
+require: rubocop-packaging  
+----
+
+Alternatively, use the following array notation when specifying multiple
+extensions:
+
+[source,yaml]
+----
+require:
+  - rubocop-other-extension
+  - rubocop-packaging
+----
+
+Now you can run `rubocop` and it will automatically load the RuboCop Packaging  
+cops together with the standard cops.
+
+== Command line
+
+[source,bash]
+----
+rubocop --require rubocop-packaging
+----
+
+== Rake task
+
+[source,ruby]
+----
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-packaging'
+end
+----