Merge pull request #1021 from mssola/man

portusctl: added man pages

.travis.yml

@@ -27,8 +27,7 @@ before_script:
   - mysql -e 'create database portus_test;'
 
 script:
-  - bundle exec rspec spec
-  - bundle exec rspec packaging/suse/portusctl/spec
+  - bundle exec rspec spec packaging/suse/portusctl/spec
   - bundle exec rubocop -V
   - bundle exec rubocop -F
   - bundle exec brakeman -z -A -x CheckUnscopedFind,CheckRender

Gemfile

@@ -85,6 +85,7 @@ unless ENV["PACKAGING"] && ENV["PACKAGING"] == "yes"
     gem "rubocop", "~> 0.41.2", require: false
     gem "brakeman", require: false
     gem "database_cleaner"
+    gem "md2man", "~>5.1.1", require: false
   end
 
   group :test do

Gemfile.lock

@@ -54,6 +54,8 @@ GEM
     bcrypt (3.1.10)
     binding_of_caller (0.7.2)
       debug_inspector (>= 0.0.1)
+    binman (5.1.0)
+      opener (>= 0.1.0, < 1)
     bootstrap-sass (3.3.5)
       autoprefixer-rails (>= 5.0.0.1)
       sass (>= 3.2.19)
@@ -184,6 +186,10 @@ GEM
     lumberjack (1.0.10)
     mail (2.6.4)
       mime-types (>= 1.16, < 4)
+    md2man (5.1.1)
+      binman (~> 5.0)
+      redcarpet (~> 3.0)
+      rouge (~> 1.0)
     method_source (0.8.2)
     mime-types (3.0)
       mime-types-data (~> 3.2015)
@@ -202,6 +208,7 @@ GEM
       shellany (~> 0.0)
     octokit (2.0.0)
       sawyer (~> 0.3.0)
+    opener (0.1.0)
     orm_adapter (0.5.0)
     paint (1.0.0)
     parser (2.3.1.2)
@@ -272,6 +279,7 @@ GEM
     redcarpet (3.3.3)
     responders (2.1.0)
       railties (>= 4.2.0, < 5)
+    rouge (1.11.1)
     rspec (3.3.0)
       rspec-core (~> 3.3.0)
       rspec-expectations (~> 3.3.0)
@@ -421,6 +429,7 @@ DEPENDENCIES
   json-schema
   jwt
   kaminari
+  md2man (~> 5.1.1)
   mysql2
   net-ldap
   poltergeist

lib/man_pages.rb

@@ -0,0 +1,40 @@
+require "md2man/roff/engine"
+
+# Defines a set of methods regarding our man pages that might be re-used in
+# different places.
+class ManPages
+  # The path were the markdown files are being stored.
+  MARKDOWN_PATH = "packaging/suse/portusctl/man/markdown".freeze
+
+  # The path were the resulting man pages are being stored.
+  MAN_PATH = "packaging/suse/portusctl/man/man1".freeze
+
+  def initialize
+    @markdown_files = Dir.glob(Rails.root.join(MARKDOWN_PATH, "*.md"))
+  end
+
+  # Render the given markdown file into a man page.
+  def render_markdown(file)
+    Md2Man::Roff::ENGINE.render(File.read(file))
+  end
+
+  # Returns the name and the path of the corresponding man page of the given
+  # markdown file.
+  def corresponding_man(file)
+    name = file.match(/\/([\w-]+)\.md/)[1]
+    path = Rails.root.join(MAN_PATH, "#{name}.1")
+    [name, path]
+  end
+
+  # Generate all the man pages.
+  def generate!
+    Rails.logger.info "Generating man pages:"
+
+    @markdown_files.each do |file|
+      output = render_markdown(file)
+      name, path = corresponding_man(file)
+      File.write path, output
+      Rails.logger.info name
+    end
+  end
+end

lib/tasks/man.rake

@@ -0,0 +1,8 @@
+require "man_pages"
+
+namespace :portus do
+  desc "Build man pages"
+  task generate_man_pages: :environment do
+    ManPages.new.generate!
+  end
+end

packaging/suse/portus.spec.in

@@ -112,6 +112,9 @@ cp packaging/suse/bin/portus_crono %{buildroot}/%{_sbindir}/
 cp packaging/suse/bin/portusctl %{buildroot}/%{_sbindir}/
 %__install -D -m 444 packaging/suse/conf/portus_crono.service %{buildroot}%{_unitdir}/portus_crono.service
 
+# Man pages
+install -d %{buildroot}%{_mandir}/man1
+install -p -m 644 packaging/suse/portusctl/man/man1/*.1 %{buildroot}%{_mandir}/man1
 
 %fdupes %{buildroot}/%{portusdir}
 
@@ -153,5 +156,7 @@ fi
 %{_sbindir}/portus_crono
 %{_sbindir}/portusctl
 %{_unitdir}/portus_crono.service
+%{_mandir}/man1/portusctl-*.1.gz
+%{_mandir}/man1/portusctl.1.gz
 
 %changelog

packaging/suse/portusctl/README.md

@@ -0,0 +1,30 @@
+# portusctl
+
+`portusctl` is the tool that is provided to RPM users in order to easily
+configure and perform operations on Portus installations. `portusctl` re-uses
+part of Portus' infrastructure, and thus it made sense to keep it in the same
+repository, and to write it in Ruby as well (at least for now that it's not too
+big or unmaintainable this way).
+
+All the commands are defined in the `lib/cli.rb` file, and the rest of the files
+are mere helpers.
+
+## man
+
+Documentation for `portusctl` comes in the form of UNIX manual pages. They can
+be found inside of the `man` directory. In this directory, there are two
+subdirectories:
+
+- `markdown`: the files that developers use to write the documentation.
+- `man1`: the manual pages that should be installed in the system.
+
+As you can see, we use regular Markdown files to edit manual pages. This is
+possible thanks to the `md2man` gem. In order to generate the resulting man
+pages inside of the `man/man1` directory, you have to execute:
+
+```
+$ rake portus:generate_man_pages
+```
+
+Note that this should be done by developers. Packagers should only have to care
+about the files inside of `man/man1` and disregard the markdown files completely.

packaging/suse/portusctl/lib/cli.rb

@@ -30,7 +30,7 @@ class Cli < Thor
     default: "DE" # gensslcert -c
   option "ssl-city",
     desc:    "SSL certificate: city",
-    default: "Nueremberg" # gensslcert -l
+    default: "Nuernberg" # gensslcert -l
   option "ssl-state",
     desc:    "SSL certificate: state",
     default: "Bayern" # gensslcert -s

packaging/suse/portusctl/man/man1/portusctl-exec.1

@@ -0,0 +1,47 @@
+.TH PORTUSCTL 1 "portusctl User manuals" "SUSE LLC." "AUGUST 2016"
+.SH NAME
+.PP
+portusctl logs \- Fetch all the logs produced by Portus
+.SH SYNOPSIS
+.PP
+\fBportusctl exec\fP <command> [arguments...]
+.SH DESCRIPTION
+.PP
+The \fBexec\fP command allows administrators to execute any command from within
+the same environment as Portus.
+.SH EXAMPLES
+.PP
+The \fBexec\fP command might come in handy when you want to execute some
+administrative command in the same context as Portus. For example, if you want
+to take a closer look at the current state of Portus, you can perform the
+following:
+.PP
+.RS
+.nf
+$ portusctl exec rails c
+.fi
+.RE
+.PP
+This will put you inside of a Ruby on Rails console with Portus' code loaded in
+it. This way, you will be able to perform deeper inspections like:
+.PP
+.RS
+.nf
+> puts Team.find_by(name: "myteam").namespaces
+.fi
+.RE
+.PP
+However, if you are not that experienced with Ruby on Rails and you want to
+check the database directly as Portus sees it, you can perform:
+.PP
+.RS
+.nf
+$ portusctl exec rails db
+.fi
+.RE
+.PP
+With the command above, you will be able to access a MariaDB prompt that is
+connected to the database that Portus is using.
+.SH HISTORY
+.PP
+August 2016, created by Miquel Sabaté Solà \[la][email protected]\[ra]

packaging/suse/portusctl/man/man1/portusctl-help.1

@@ -0,0 +1,13 @@
+.TH PORTUSCTL 1 "portusctl User manuals" "SUSE LLC." "AUGUST 2016"
+.SH NAME
+.PP
+portusctl help \- Show a help message for the given command
+.SH SYNOPSIS
+.PP
+\fBportusctl help\fP <command>
+.SH DESCRIPTION
+.PP
+The \fBhelp\fP command shows a help message for the given command.
+.SH HISTORY
+.PP
+August 2016, created by Miquel Sabaté Solà \[la][email protected]\[ra]

packaging/suse/portusctl/man/man1/portusctl-logs.1

@@ -0,0 +1,17 @@
+.TH PORTUSCTL 1 "portusctl User manuals" "SUSE LLC." "AUGUST 2016"
+.SH NAME
+.PP
+portusctl logs \- Fetch all the logs produced by Portus
+.SH SYNOPSIS
+.PP
+\fBportusctl logs\fP
+.SH DESCRIPTION
+.PP
+The \fBlogs\fP command fetches all the logs related to Portus. These logs might be
+system logs, logs produced by Portus, etc. This command is useful when
+investigating an issue in your Portus instance.
+.PP
+The logs will be stored in a temporary file in the \fB\fC/tmp\fR directory.
+.SH HISTORY
+.PP
+August 2016, created by Miquel Sabaté Solà \[la][email protected]\[ra]

packaging/suse/portusctl/man/man1/portusctl-make-admin.1

@@ -0,0 +1,26 @@
+.TH PORTUSCTL 1 "portusctl User manuals" "SUSE LLC." "AUGUST 2016"
+.SH NAME
+.PP
+portusctl make_admin \- Grant a user administrator privileges
+.SH SYNOPSIS
+.PP
+\fBportusctl make_admin\fP [arguments...]
+.SH DESCRIPTION
+.PP
+The \fBmake_admin\fP command allows administrators to grant administrator
+privileges to a user. That being said, you can perform this command without
+specifying any user name. If you do that, then you will get a list of users in
+the system. If you pass a user name, it will grant administrator privileges to
+this selected user. Note that \fBmake_admin\fP is \fIequivalent\fP of doing:
+.PP
+.RS
+.nf
+$ portusctl rake make_admin[username]
+.fi
+.RE
+.PP
+We are providing this command for the convenience of avoiding rake\-specific
+syntax to users that are not experience with either Ruby or Ruby on Rails.
+.SH HISTORY
+.PP
+August 2016, created by Miquel Sabaté Solà \[la][email protected]\[ra]

packaging/suse/portusctl/man/man1/portusctl-rake.1

@@ -0,0 +1,49 @@
+.TH PORTUSCTL 1 "portusctl User manuals" "SUSE LLC." "AUGUST 2016"
+.SH NAME
+.PP
+portusctl rake \- Execute rake commands available within Portus
+.SH SYNOPSIS
+.PP
+\fBportusctl rake\fP <task> [arguments...]
+.SH DESCRIPTION
+.PP
+The \fBrake\fP command allows administrators to execute rake tasks that are
+available within the Portus context. Some of these tasks have been defined by
+Portus developers, and some others are plain tasks defined by Ruby on Rails or
+some other gem. In order to get the full list of all the available tasks,
+execute:
+.PP
+.RS
+.nf
+$ portusctl rake \-T
+.fi
+.RE
+.PP
+It is not recommended to execute any rake task if you are not experienced with
+Portus or you are on a production server.
+.SH EXAMPLES
+.PP
+As shown in the description, "portusctl rake \-T" will give you the available
+tasks. Moreover, as it's been also explained in the description section, these
+tasks are advanced and should be used with caution. That being said, there is at
+least one task that is really useful:
+.PP
+.RS
+.nf
+$ portusctl rake portus:info
+.fi
+.RE
+.PP
+The previous task will give you detailed output of:
+.RS
+.IP \(bu 2
+The exact version of Portus that you are running.
+.IP \(bu 2
+The configuration being used (with sensible information hidden).
+.RE
+.PP
+This task is really useful to give developers more information when fixing an
+issue that you might be having.
+.SH HISTORY
+.PP
+August 2016, created by Miquel Sabaté Solà \[la][email protected]\[ra]