ascii_binder 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24f0d4eedad5a44476a05c8b2dfe80341974779e
-  data.tar.gz: 8efa57a740e9c2f879f02f9e55abd63ea1985080
+  metadata.gz: f398f6483700ae88e771ccc52b00b844bf022d26
+  data.tar.gz: c731c4527a8d4ed3b25e648e81f68df1d6ba73d4
 SHA512:
-  metadata.gz: b286233ac388b2ab379f46d0d0125d12c30260dd0692f2a199d8f9b4ddbe7ebea8ddacd8e803e27960981fe0116b4e89b3f172e880f5a27974ef36e6bbcf4928
-  data.tar.gz: b622ed29d46c457b40970660083b58ccf4d56c43201a113b392419c563d7857fb4b36a0853f9ee88e0461b64c97fa1054975564a19951d48a6b9bb37054a288c
+  metadata.gz: bc7d71d067ff2d9d95e1182e2b28d2823406377211ec3568dec80d4bce8a4f0175b6b842ba89a0bb3345e7dc78832e444ed2f11eb0ab7cc2ebd805615e3c3a92
+  data.tar.gz: afc5125f133cc38883091f77e3900d02ec496286b4847e36bec55f1307367712c70554e4070694f91113ebe2eaa9d1f177e4de124bc948e327b033c4e3efc270

data/README.adoc

@@ -1,221 +1,14 @@
 = AsciiBinder
 
-This repo contains the documentation for
+image:https://badge.fury.io/rb/ascii_binder.svg["Gem Version", link="https://badge.fury.io/rb/ascii_binder"]
 
-* http://origin.openshift.com/[OpenShift Origin]
-* http://openshift.com/[OpenShift Online]
-* http://www.redhat.com/products/cloud-computing/openshift-enterprise/[OpenShift Enterprise]
+This repo contains the source code for AsciiBinder, a documentation system for complex software projects. To learn more about AsciiBinder:
 
-The documentation is sourced in http://www.methods.co.nz/asciidoc/[AsciiDoc] and transformed into HTML/CSS and other formats through http://asciidoctor.org/[AsciiDoctor]-based automation.
+* Have a gander at the http://www.asciibinder.org/latest/welcome/[AsciiBinder documentation]
+* Or just take the https://rubygems.org/gems/ascii_binder[ascii_binder Ruby Gem] for a spin
 
-== Repo Organization
+The AsciiBinder system was initially developed for https://github.com/openshift/openshift-docs[OpenShift documentation], but has been revised to work for documenting a wide variety of complex, multi-versioned software projects.
 
-Each directory of the repo represents a different collection of topics (you can think of directories as books). The exceptions to this rule are directories whose names start with an underscore (like `_builder_lib` and `_javascripts`), which contain the assets used to generate the finished documentation. Within each 'book' directory, topics exist as separate asciidoc files and an `images` directory contains any images that are included in the topics.
+== Contributing
+We are using the https://github.com/redhataccess/ascii_binder/issues[Issues] page to track bugs and feature ideas on the code, so have a look and feel free to ask questions there. You can also follow / chat with us on Twitter - https://twitter.com/AsciiBinder[@AsciiBinder]
 
-----
-/
-/book1
-/book1/topic1.adoc
-/book1/topicN.adoc
-/book1/images
-/book1/images/img1.png
-/book1/images/imgN.png
-...
-/bookN
-----
-
-== Version Management
-The overlap of documentation across OpenShift Origin, Online and Enterprise is no less than 80%. In many cases, this means that individual topics may need to include or exclude individual paragraphs with respect to a specific OpenShift distribution. While it is _possible_ to accomplish this solely by using git branches to maintain slightly different versions of a given topic, doing so would make the task of maintaining internal consistency extremely difficult for content contributors.
-
-Git branching is still extremely valuable, and serves the important role of tracking the release versions of documentation for the various OpenShift distributions.
-
-=== Distribution-Specific Conditionals
-OpenShift documentation uses AsciiDoc's `ifdef/endif` macro to conditionalize document segments for specific OpenShift distributions down to the single-line level.
-
-The supported distribution attributes used in the OpenShift document generator are:
-
-* `openshift-origin`
-* `openshift-online`
-* `openshift-enterprise`
-
-These attributes can be used alone or together to conditionalize text within a topic document.
-
-Here is an example of this concept in use:
-
-----
-This first line is unconditionalized, and will appear for all versions.
-
-\ifdef::openshift-online[]
-This line will only appear for OpenShift Online.
-\endif::[]
-
-\ifdef::openshift-enterprise[]
-This line will only appear for OpenShift Enterprise.
-\endif::[]
-
-\ifdef::openshift-origin,openshift-enterprise[]
-This line will appear for OpenShift Origin and Enterprise, but not for OpenShift Online.
-\endif::[]
-----
-
-Two important points to keep in mind:
-
-* The `ifdef/endif` blocks have no size limit, however they should _not_ be used to conditionalize an entire topic. If an entire topic file is specific to a given OpenShift distribution, refer to the link:#document-set-metadata[Document Set Metadata] section for information on how to conditionalize at the whole-topic level.
-
-* The `ifdef/endif` blocks _cannot be nested_. In other words, one conditional block cannot contain other conditional blocks.
-
-=== Release Branches
-Through the use of link:#distribution-specific-conditionals[Distribution-Specific Conditionals] and link:#document-set-metadata[Document Set Metadata], the master branch of this repository always contains a complete set of documentation that includes all of the OpenShift distributions. However, when and as new versions of the OpenShift distros are released, the master branch is merged down to new or existing release branches. Here is the general naming scheme used in the branches:
-
-* `master` - OpenShift Origin latest code
-* `origin-N.N` - OpenShift Origin most recent stable release
-* `online` - OpenShift Online most recent release
-* `enterprise-N.N` - OpenShift Enterprise support releases
-
-On a nightly basis, the documentation web sites are rebuilt for each of these branches. In this manner, documentation for released versions of OpenShift will remain the same even as development continues on master. Additionally, any corrections or additions that are "cherry-picked" into the release branches will show up in the release documentation the next day.
-
-== Document Set Metadata
-In order to construct the documentation site from these sources, the build system looks at the `_build_cfg.yml` metadata file. The build system _only_ looks in this file for information on which files to include, so any new file submissions must be accompanied by an update to this metadata file.
-
-=== File Format
-The format of this file is as indicated:
-
-----
---- <1>
-Name: Origin of the Species <2>
-Dir:  origin_of_the_species <3>
-Distros: all <4>
-Topics:
-  - Name: The Majestic Marmoset <5>
-    File: the_majestic_marmoset <6>
-    Distros: all
-  - Name: The Curious Crocodile
-    File: the_curious_crocodile
-    Distros: openshift-online,openshift-enterprise <7>
-  - Name: The Numerous Nematodes
-    Dir: the_numerous_nematodes <8>
-    Topics:
-      - Name: The Wily Worm <9>
-        File: the_wily_worm
-      - Name: The Acrobatic Ascarid  <= Sub-topic 2 name
-        File: the_acrobatic_ascarid  <= Sub-topic 2 file under <group dir>/<subtopic dir>
-----
-<1> Record separator at the top of each topic group
-<2> Display name of topic group
-<3> Directory name of topic group
-<4> Which OpenShift versions this topic group is part of
-<5> Topic name
-<6> Topic file under the topic group dir without '.adoc'
-<7> Which OpenShift versions this topic is part of
-<8> This topic is actually a subtopic group. Instead of a `File` path it has a `Dir` path and `Topics`, just like a top-level topic group.
-<9> Topics belonging to a subtopic group are listed just like regular topics with a `Name` and `File`.
-
-=== Notes on "Distros"
-
-* The "Distros" setting is optional for topic groups and topic items. When the "Distros" setting is absent, the system treats the topic group or topic as though the user had set "Distros: all".
-* The "all" value for "Distros" is a synonym for "openshift-origin,openshift-enterprise,openshift-online".
-* The "all" value trumps other values, so "openshift-online,all" is treated as "all"
-
-== Understanding the Complete Distribution Condition Chain
-It is important to understand the ordering of distribution conditionals in determining whether or not a specific piece of content appears in the documentation set. The hierarchy is fairly straightforward:
-
-1. Topic group "Distros" setting from `_build_cfg.yml`
-2. Topic item "Distros" setting from `_build_cfg.yml`
-3. Document-level `ifdef/endif` blocks
-
-In this manner:
-
-* If a topic group is configured with "Distros: openshift-online", the entire group will be skipped for OpenShift Enterprise and OpenShift Origin, regardless of the Topic-level and document-level content rules within that group.
-
-* When a topic group is available to all Distros, but a specific topic item is limited, the topic group will appear for all distros and the specific topic item will only appear for the indicated distros.
-
-== Live Editing
-If you would like to work on one of the documentation files in an editing environment that automatically redraws the resulting HTML, follow these steps.
-
-=== Prerequisites
-You will need the following tools in your editing environment:
-
-* A bash shell environment (Linux distributions and OS X include these out of the box, for Windows consider http://cygwin.com/[Cygwin])
-* https://www.ruby-lang.org/en/[Ruby]
-* http://www.git-scm.com/[git]
-* A web browser (Firefox, Chrome or Safari) with the http://livereload.com/[LiveReload] extension
-
-With these tools available, first perform a one-time setup:
-
-1. Clone the https://github.com/openshift/openshift-docs[openshift-docs] repo from GitHub:
-+
-----
-$ git clone https://github.com/openshift/openshift-docs.git
-----
-2. From the cloned directory, run a bundle install:
-+
-----
-$ cd openshift-docs
-$ bundle install
-----
-+
-TIP: If you don't have bundler installed, you can get it by running `gem install bundler`
-
-That's it for setup, the next section explains how to run the LiveReload system.
-
-=== Running with LiveReload
-Once you've installed the link:#prerequisites[prerequisites] you can fire up the LiveReload setup as follows:
-
-1. From the `openshift-docs` directory, run a preliminary build:
-+
-----
-$ cd openshift-docs
-$ bundle exec rake build
-----
-2. Now open the generated HTML file in your browser. It will be under `openshift-docs/_preview/<distro>/<branch>` with the same path and filename as the original file. The only difference will be the name ending in '.html' instead of '.adoc'.
-3. Now start up the `guard` utility:
-+
-----
-$ bundle exec guard
-----
-+
-TIP: This utility will run in the terminal where you started it, so you should leave it running off to the side and use other terminals for regular tasks.
-4. Finally, back in your browser, enable the LiveReload plugin in the same tab where the preview file is displayed. You will know this step succeeded if the LiveReload icon changes, and if you see output similar to the following in the terminal where `guard` is running:
-+
-----
-[1] guard(main)> 17:29:22 - INFO - Browser connected.
-----
-
-That's it. Now any changes that you make to the source file will automatically trigger a rebuild of the target HTML file.
-
-=== Clean Up
-The `.gitignore` file is set up to prevent anything under `_preview` and `_package` from being committed. However, you can reset the environment manually by running:
-
-----
-$ bundle exec rake clean
-----
-
-== Creating New Topic Pages
-The layout and style rules for new documentation are largely described in an upcoming style guide (delivery date TBD). However, a few important rules are listed here because they affect the way that the pages are rendered.
-
-The top matter of any new topic page must have the following format:
-
-----
-= Human-Readable Topic Title
-{product-author}
-{product-version}
-:data-uri:
-:icons:
-----
-
-* The article title goes on the first line with a level 1 header markup (=)
-* The [x-]`{product-author}` and [x-]`{product-version}` are AsciiDoc attributes that get replaced dynamically when the docs are generated.
-* The `:data-uri:` attribute tells AsciiDoctor to embed any images directly in the HTML.
-* The `:icons:` attribute tells AsciiDoctor to use cool icons for admonition blocks.
-
-After the heading block and a single whitespace line, you can include any content for the topic.
-
-NOTE: Any section headers within the article must be level 2 (==) or lower. Try to be consistent about level-nesting; it won't break AsciiDoctor to jump from a level 1 section header down to level 3, but it isn't good form.
-
-
-== Contacts
-
-For questions or comments about the documentation system:
-
-* OpenShift team members can be found on the http://webchat.freenode.net/?randomnick=1&channels=openshift&uio=d4[#openshift] and http://webchat.freenode.net/?randomnick=1&channels=openshift-dev&uio=d4[#openshift-dev channels] on http://www.freenode.net/[FreeNode].
-* You can also join the http://lists.openshift.redhat.com/openshiftmm/listinfo/users[Users] or http://lists.openshift.redhat.com/openshiftmm/listinfo/dev[Developers] mailing list.

data/ascii_binder.gemspec

@@ -6,11 +6,11 @@ require 'ascii_binder/version'
 Gem::Specification.new do |spec|
   spec.name          = "ascii_binder"
   spec.version       = AsciiBinder::VERSION
-  spec.authors       = ["N. Harrison Ripps"]
-  spec.email         = ["nhr@redhat.com"]
+  spec.authors       = ["N. Harrison Ripps","Jason Frey"]
+  spec.email         = ["nhr@redhat.com","jfrey@redhat.com"]
   spec.summary       = %q{Builder for multi product documention websites.}
   spec.description   = %q{Builder for multi product documention websites.}
-  spec.homepage      = "http://github.com/redhataccess/ascii_binder"
+  spec.homepage      = "http://asciibinder.org/"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/bin/ascii_binder

@@ -0,0 +1,226 @@
+#!/usr/bin/env ruby
+
+require 'ascii_binder/helpers'
+require 'pathname'
+require 'trollop'
+
+include AsciiBinder::Helpers
+
+def call_generate(distro,page=nil)
+  if page == ''
+    page = nil
+  end
+  begin
+    generate_docs(distro,page)
+  rescue Exception => e
+    Trollop::die "Could not generate docs: #{e.message}"
+  end
+end
+
+SUB_COMMANDS = %w{help build watch package clean create}
+Trollop::options do
+  banner <<-EOF
+Usage:
+  #$0 <command> <repo_dir>
+
+Commands:
+  build (default action)
+    Builds the HTML docs in the indicated repo dir
+  create
+    Generates a new AsciiBinder repo at the indicated dir
+  watch
+    Starts Guard, which automatically regenerates changed HTML
+    files on the working branch in the repo dir
+  package
+    Builds and packages the static HTML for all of the sites
+    defined in the _distro_config.yml file
+  clean
+    Remove _preview, _publish and _package dirs created by
+    other AsciiBinder operations.
+
+Options:
+EOF
+  stop_on SUB_COMMANDS
+end
+
+cmd = ARGV.shift
+repo_dir = nil
+
+if cmd.nil?
+  cmd = "build"
+elsif not SUB_COMMANDS.include?(cmd)
+  if not ARGV.empty?
+    Trollop::die "'#{cmd}' is not a valid asciibinder subcommand. Legal values are '#{SUB_COMMANDS.join('\', \'')}'."
+  else
+    repo_dir = Pathname.new(cmd)
+    cmd = "build"
+  end
+end
+
+cmd_opts = case cmd
+  when "build"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 build <options> <repo_dir>
+
+Description:
+  This is the default behavior for the asciibinder utility. When run,
+  AsciiBinder reads the _distro_config.yml file out of the working
+  branch of the indicated repo directory and based on that, proceeds to
+  build the working branch version of the documentation for each distro.
+
+  Once the working branch version is built, AsciiBinder cycles through
+  the other branches named in the _distro_config.yml file until all of
+  the permutations have been built.
+
+  The available options enable you to limit the scope of the build work,
+  as described by the options themselves. Note that the format for the
+  "--page" option is:
+
+  <topic_group>:<topic_file>
+
+  or for subtopics:
+
+  <topic_group>/<subtopic_group>:<topic_file>
+
+  However, if you want to use the --page option extensively, then be
+  aware of the `asciibinder watch` function, which does this for you
+  automatically as you change .adoc files in your working branch.
+
+Options:
+EOF
+      opt :distro, "Instead of building all distros, build branches only for the specified distro.", :default => ''
+      opt :page, "Build only the specified page for all distros and only the current working branch.", :default => ''
+      conflicts :distro, :page
+    end
+  when "create"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 create <new_repo_dir>
+
+Description:
+  Creates a new, bare AsciiBinder repo in the specified directory.
+EOF
+    end
+  when "watch"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 watch <repo_dir>
+
+Description:
+  In watch mode, AsciiBinder starts a Guard process in the foreground.
+  This process watches the repo_dir for changes to the AsciiDoc (.adoc)
+  files. When a change occurs, AsciiBinder regenerates the specific
+  HTML output of the file that was changed, for the working branch only.
+
+  This is the equivalent of running:
+
+  $ asciibinder build --page='<topic_group>:<affected_file>'
+
+  ...except that the Guardfile automatically detects and runs this as
+  you work.
+
+  This is meant to be used in conjunction with a web browser that is
+  running a LiveReload plugin. If you are viewing the output HTML page
+  in a browser where LiveReload is active, then every time you save a
+  new version of the .adoc file, the new HTML is automatically
+  regenerated and your page view is automatically refreshed.
+EOF
+    end
+  when "package"
+    Trollop::options do
+      banner <<-EOF
+Usage:
+  #$0 package <options> <repo_dir>
+
+Description:
+  Publish mode is similar to 'build' mode, but once all of the branches' of
+  HTML are generated, 'publish' goes on to organize the branch / distro
+  combinations that are described in _distro_config.yml into their "site"
+  layouts. As a final step, the site layouts are tarred and gzipped for
+  easy placement onto a production web server.
+
+Options:
+EOF
+      opt :site, "Instead of packaging every docs site, package the specified site only.", :default => ''
+    end
+  when "help"
+    Trollop::educate
+  end
+
+if (not repo_dir.nil? and not ARGV.empty?) or (repo_dir.nil? and ARGV.length > 1)
+  Trollop::die "Too many arguments provided to ascii_binder: '#{ARGV.join(' ')}'. Exiting."
+elsif repo_dir.nil?
+  if ARGV.length == 1
+    repo_dir = Pathname.new(ARGV.shift)
+  else
+    if not cmd == 'create'
+      repo_dir = Pathname.pwd
+    else
+      Trollop::die "Specify a name for the new repo directory."
+    end
+  end
+end
+
+# Validate the repo_dir path
+if cmd == 'create'
+  if repo_dir.exist?
+    Trollop::die "The specified new repo directory '#{repo_dir}' already exists."
+  end
+else
+  if not repo_dir.exist?
+    Trollop::die "The specified repo directory '#{repo_dir}' does not exist."
+  elsif not repo_dir.directory?
+    Trollop::die "The specified repo directory path '#{repo_dir}' is not a directory."
+  elsif not repo_dir.readable?
+    Trollop::die "The specified repo directory '#{repo_dir}' is not readable."
+  elsif not repo_dir.writable?
+    Trollop::die "The specified repo directory '#{repo_dir}' cannot be written to."
+  else
+    ['.git','_build_cfg.yml','_distro_map.yml','_templates'].each do |file|
+      if not File.exist?(File.join(repo_dir, file))
+        Trollop::die "The specified repo directory '#{repo_dir}' does not appear to be an AsciiBinder repo."
+      end
+    end
+  end
+end
+
+# Set the repo root
+set_source_dir(File.expand_path(repo_dir))
+
+# Change to the repo dir. This is necessary in order for
+# AsciiDoctor to work properly.
+if not cmd == 'create'
+  Dir.chdir source_dir
+end
+
+# Do the things with the stuff
+case cmd
+when "build"
+  build_distro = cmd_opts[:build] || ''
+  refresh_page = cmd_opts[:page] || ''
+  call_generate(build_distro,refresh_page)
+when "package"
+  clean_up
+  call_generate('')
+  package_site = cmd_opts[:site] || ''
+  package_docs(package_site)
+when "watch"
+  if not dir_empty?(preview_dir)
+    guardfile_path = File.join(Gem::Specification.find_by_name("ascii_binder").full_gem_path, 'Guardfile')
+    exec("guard -G #{guardfile_path}")
+  else
+    Trollop::die "Run 'asciibinder build' at least once before running 'asciibinder watch'."
+  end
+when "clean"
+  clean_up
+  puts "Cleaned up #{repo_dir}."
+when "create"
+  create_new_repo
+  puts "Created new repo in #{repo_dir}."
+end
+
+exit