(maint) Add Github pages documentation website

Author: glennsarti

_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-midnight

docs/.gitignore

@@ -0,0 +1,3 @@
+_site
+.sass-cache
+.jekyll-metadata

docs/404.html

@@ -0,0 +1,24 @@
+---
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

docs/Gemfile

@@ -0,0 +1,22 @@
+source ENV['GEM_SOURCE'] || "https://rubygems.org"
+
+gem "rake"
+
+if Gem.win_platform?
+  # Jekyll really hates Windows :-(  Need to use WSL instead
+  raise 'Jekyll really hates Windows :-(  Need to use WSL instead'
+end
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", group: :jekyll_plugins
+
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.6"
+end
+
+# Evaluate Gemfile.local if it exists
+if File.exists? "#{__FILE__}.local"
+  eval(File.read("#{__FILE__}.local"), binding)
+end

docs/Rakefile

@@ -0,0 +1,63 @@
+is_windows = (ENV['OS'] == 'Windows_NT')
+
+# clean settings
+desc 'Clean'
+task :clean do
+  puts 'Cleaning Jekyll'
+  system 'jekyll clean'
+end
+
+basicSettings = '--trace --safe --host=0.0.0.0'
+devConfig = '--config _config.yml,_config.dev.yml --unpublished --future'
+
+namespace :build do
+  desc 'Build Jekyll with production settings'
+  task :prod => [:clean] do
+    puts 'Building Jekyll with PRODUCTION settings...'
+    system "JEKYLL_ENV=production jekyll build #{basicSettings} --no-watch"
+  end
+
+  desc 'Build Jekyll with development settings'
+  task :dev do
+    puts 'Building Jekyll with DEVELOPMENT settings...'
+    system "JEKYLL_ENV=development jekyll build #{basicSettings} #{devConfig} --no-watch"
+  end
+end
+
+namespace :serve do
+  desc 'Serve Jekyll with production settings'
+  task :prod => [:clean] do
+    puts 'Building Jekyll with PRODUCTION settings...'
+    if is_windows then
+      ENV['JEKYLL_ENV'] = "production"
+      system "jekyll serve #{basicSettings}"
+    else
+      system "JEKYLL_ENV=production jekyll serve #{basicSettings}"
+    end
+  end
+
+  desc 'Serve Jekyll with development settings'
+  task :dev => [:clean] do
+    puts 'Building Jekyll with DEVELOPMENT settings...'
+    if is_windows then
+      ENV['JEKYLL_ENV'] = "development"
+      system "jekyll serve #{basicSettings} #{devConfig}"
+    else
+      system "JEKYLL_ENV=development jekyll serve #{basicSettings} #{devConfig}"
+    end
+  end
+
+end
+
+namespace :watch do
+  desc 'Serve and watch Jekyll with development settings'
+  task :dev => [:clean] do
+    puts 'Building Jekyll with DEVELOPMENT settings...'
+    if is_windows then
+      ENV['JEKYLL_ENV'] = "development"
+      system "jekyll serve #{basicSettings} #{devConfig} --livereload --incremental"
+    else
+      system "JEKYLL_ENV=development jekyll serve --incremental #{basicSettings} #{devConfig} --livereload"
+    end
+  end
+end

docs/_config.dev.yml

@@ -0,0 +1 @@
+---

docs/_config.yml

@@ -0,0 +1,46 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+title: Puppetfile Resolver
+email:
+description: Dependency resolver for Puppet Modules and Puppetfiles, as a gem!
+baseurl: "/puppetfile-resolver" # the subpath of your site, e.g. /blog
+url: "https://glennsarti.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+twitter_username: glennsarti
+github_username: glennsarti
+
+theme: jekyll-theme-cayman
+#theme: cayman
+
+# Build settings
+markdown: kramdown
+plugins:
+  - jekyll-feed
+  - jekyll-github-metadata
+
+# Github Info
+repository: "glennsarti/puppetfile-resolver"
+
+# Exclude from processing.
+# The following items will not be processed, by default. Create a custom list
+# to override the default setting.
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/

docs/_includes/sections.md

@@ -0,0 +1,5 @@
+{% if page.title == "Puppetfile Resolver" %}- About{% else %}- [About](.){% endif %}
+{% if page.title == "Architecture" %}- Architecture{% else %}- [Architecture](./architecture){% endif %}
+{% if page.title == "Parsers" %}- Parsers{% else %}- [Parsers](./parsers){% endif %}
+{% if page.title == 'Example Usage' %}- Example Usage{% else %}- [Example Usage](./example_usage){% endif %}
+{% if page.title == 'Known Issues' %}- Known Issues{% else %}- [Known Issues](./known_issues){% endif %}

docs/architecture.md

@@ -0,0 +1,141 @@
+---
+---
+
+# Architecture
+
+{% include sections.md %}
+
+---
+
+## Why a library and not a CLI tool?
+
+Due to all of the different needs of tool developers, this is offered as a library instead of full blown CLI tool. For example, the needs of a VSCode Extensions developer are very different than that of the Puppet Developer Kit developer.
+
+Therefore this is a library which is intended to be used by tool developers to create useful tools for users, and not really for direct use by users.
+
+Note that a CLI is included (`puppetfile-cli.rb`) only as an example of how to create a tool using this library.
+
+## Architecture
+
+``` text
+                    +-----------------+   +-----------------+   +-----------------+
+                    | Forge Searcher  |   | Github Searcher |   | Local Searcher  |
+                    +-------+---------+   +--------+--------+   +-------+---------+
+                            |                      |                    |
+                            +----------------------+--------------------+
+                                                   |
+                                                   |
+                                                   V
+            +--------+                        +----------+                          +-------------------+
+-- Text --> | Parser | -- Document Model -+-> | Resolver | -- Dependency Graph -+-> | Resolution Result |
+            +--------+                    |   +----------+                      |   +-------------------+
+                                          |                                     |
+                                          |                                     |
+                                          V                                     V
+                                    +-----------+                         +------------+
+                                    | Document  |                         | Resolution |
+                                    | Validator |                         | Validator  |
+                                    +-----------+                         +------------+
+```
+
+### Workflow
+
+The workflow of the library is, hopefully, straightforward:
+
+1. A list of modules needed, typically expressed as a Puppetfile is parsed into a Document Model.  This model means that additional parsers can be added a later time, or users can craft their own Document Model and not need a parser at all. See _Creating a document model_ below for more information.
+
+2. The Document Model can then, optionally, be validated
+
+3. The Resolver can then be called on the Document Model, which outputs a Resolution Result (if successful) or an appropriate error
+
+4. The Resolution Result can also be validated according to Puppetfile rules. For example, it must not include modules which were not declared in the Puppetfile.
+
+### Puppetfile Parser
+
+The parser converts the content of a Puppetfile into a document model (`PuppetfileResolver::Puppetfile::Document`).
+
+See [Parsers](./parsers) for more information about the available parsers.
+
+### Creating a document model
+
+A user of the library can craft a document model object in any fashion they require. To do so, first the user needs to create a blank document model (`PuppetfileResolver::Puppetfile::Document.new('')`), and call `add_module` with an appropriately created module definition:
+
+- `PuppetfileResolver::Puppetfile::ForgeModule`
+- `PuppetfileResolver::Puppetfile::GitModule`
+- `PuppetfileResolver::Puppetfile::LocalModule`
+- `PuppetfileResolver::Puppetfile::SvnModule`
+
+Note that the `PuppetfileResolver::Puppetfile::InvalidModule` class should not really be used as it will cause validation errors. Typically this is used by parsers to express that it found a module definition but it could not determine the type of module it is.
+
+A complete example is shown below, where it creates a document of all the latest modules in the `module_list` array
+
+``` ruby
+module_list = ['puppetlabs/stdlib']
+
+# Build the document model from the module names, defaulting to the latest version of each module
+model = PuppetfileResolver::Puppetfile::Document.new('')
+module_list.each do |mod_name|
+  model.add_module(
+    PuppetfileResolver::Puppetfile::ForgeModule.new(mod_name).tap { |mod| mod.version = :latest }
+  )
+end
+```
+
+
+### Puppetfile Document Validation
+
+Even though a Puppetfile can be parsed, doesn't mean it's valid. For example, defining a module twice.
+
+### Puppetfile Resolution
+
+Given a Puppetfile document model, the library can attempt to recursively resolve all of the modules and their dependencies. The resolver be default will not be strict, that is, missing dependencies will not throw an error, and will attempt to also be resolved. When in strict mode, any missing dependencies will throw errors.
+
+### Module Searchers
+
+The Puppetfile resolution needs information about all of the available modules and versions, and does this through calling various Specification Searchers. Currently Puppet Forge, Github and Local FileSystem searchers are implemented. Additional searchers could be added, for example GitLab or SVN.
+
+The result is a dependency graph listing all of the modules, dependencies and version information.
+
+### Resolution validation
+
+Even though a Puppetfile can be resolved, doesn't mean it is valid. For example, missing module dependencies are not considered valid.
+
+### Dependency Graph
+
+The resolver uses the [Molinillo](https://github.com/CocoaPods/Molinillo) ruby gem for dependency resolution. Molinillo is used in Bundler, among other gems, so it's well used and maintained project.
+
+### Example usage
+
+``` ruby
+puppetfile_path = '/path/to/Puppetfile'
+
+# Parse the Puppetfile into an object model
+content = File.open(puppetfile_path, 'rb') { |f| f.read }
+require 'puppetfile-resolver/puppetfile/parser/r10k_eval'
+puppetfile = ::PuppetfileResolver::Puppetfile::Parser::R10KEval.parse(content)
+
+# Make sure the Puppetfile is valid
+unless puppetfile.valid?
+  puts 'Puppetfile is not valid'
+  puppetfile.validation_errors.each { |err| puts err }
+  exit 1
+end
+
+# Create the resolver
+# - Use the document we just parsed (puppetfile)
+# - Don't restrict by Puppet version (nil)
+resolver = PuppetfileResolver::Resolver.new(puppetfile, nil)
+
+# Configure the resolver
+cache                 = nil  # Use the default inmemory cache
+ui                    = nil  # Don't output any information
+module_paths          = []   # List of paths to search for modules on the local filesystem
+allow_missing_modules = true # Allow missing dependencies to be resolved
+opts = { cache: cache, ui: ui, module_paths: module_paths, allow_missing_modules: allow_missing_modules }
+
+# Resolve
+result = resolver.resolve(opts)
+
+# Output resolution validation errors
+result.validation_errors.each { |err| puts "Resolution Validation Error: #{err}\n"}
+```

docs/assets/css/style.scss

@@ -0,0 +1,4 @@
+---
+---
+
+@import "{{ site.theme }}";

docs/example_usage.md

@@ -0,0 +1,44 @@
+---
+---
+
+# Example Usage
+
+{% include sections.md %}
+
+---
+
+This example reads in a Puppet file from `'/path/to/Puppetfile'` and outputs any validation errors to the console
+
+``` ruby
+puppetfile_path = '/path/to/Puppetfile'
+
+# Parse the Puppetfile into an object model
+content = File.open(puppetfile_path, 'rb') { |f| f.read }
+require 'puppetfile-resolver/puppetfile/parser/r10k_eval'
+puppetfile = ::PuppetfileResolver::Puppetfile::Parser::R10KEval.parse(content)
+
+# Make sure the Puppetfile is valid
+unless puppetfile.valid?
+  puts 'Puppetfile is not valid'
+  puppetfile.validation_errors.each { |err| puts err }
+  exit 1
+end
+
+# Create the resolver
+# - Use the document we just parsed (puppetfile)
+# - Don't restrict by Puppet version (nil)
+resolver = PuppetfileResolver::Resolver.new(puppetfile, nil)
+
+# Configure the resolver
+cache                 = nil  # Use the default inmemory cache
+ui                    = nil  # Don't output any information
+module_paths          = []   # List of paths to search for modules on the local filesystem
+allow_missing_modules = true # Allow missing dependencies to be resolved
+opts = { cache: cache, ui: ui, module_paths: module_paths, allow_missing_modules: allow_missing_modules }
+
+# Resolve
+result = resolver.resolve(opts)
+
+# Output resolution validation errors
+result.validation_errors.each { |err| puts "Resolution Validation Error: #{err}\n"}
+```

docs/index.md

@@ -0,0 +1,28 @@
+---
+title: "Puppetfile Resolver"
+layout: default
+---
+[![Open Issues](https://img.shields.io/github/issues/glennsarti/puppetfile-resolver)](https://github.com/glennsarti/puppetfile-resolver/issues)
+[![License](https://img.shields.io/github/license/glennsarti/puppetfile-resolver)](https://github.com/glennsarti/puppetfile-resolver)
+[![Gem Version](https://img.shields.io/gem/v/puppetfile-resolver)](https://rubygems.org/gems/puppetfile-resolver)
+
+{% include sections.md %}
+
+---
+
+# Puppetfile Resolver
+
+The [Puppetfile](https://puppet.com/docs/pe/latest/puppetfile.html) is used by Puppet to manage the collection of modules used by a Puppet master. The Puppetfile is then used by tools like [R10K](https://github.com/puppetlabs/r10k) and [Code Manager](https://puppet.com/docs/pe/latest/code_mgr_how_it_works.html#how-code-manager-works) to download and install the required modules.
+
+However, the Puppetfile is designed to have explicit dependencies, that is, **all** modules and **all** of the dependencies must be specified in Puppetfile. This is very different to formats like `Gemfile` (Ruby) or `package.json` (NodeJS) where dependencies are brought in as needed.
+
+Using explicit dependencies is great in a configuration management system like Puppet, but it puts the burden on updates onto the user.
+
+This library includes all of the code to parse a Puppetfile and then calculate a dependency graph to try and resolve all of the module dependencies and versions. The resolver can also restrict on Puppet version, for example, only Modules which support Puppet 6.
+
+**Note** This library is in active development!
+
+## To Do
+
+- Could do with more tests
+- Add YARD documentation