Merge branch 'master' of https://github.com/puppetlabs/puppet-docs

Author: loganmantyla

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "01:00"
+  open-pull-requests-limit: 10
+

.gitignore

@@ -18,7 +18,6 @@ puppetdocs-latest.tar.gz*
 .bundle
 externalsources
 _cache
-Gemfile.lock
 .*.swo
 .*.swp
 .*.un~
@@ -29,3 +28,4 @@ Gemfile.lock
 link_test_results.yaml
 link_report.txt
 .yardoc
+puppet-docs-build.log

Gemfile

@@ -1,34 +1,34 @@
 source 'https://rubygems.org/'
 gemspec :name => 'puppet_docs'
 
-gem 'versionomy'
-gem 'rake'
-gem 'rack', '~> 1.6' # We don't want Rack 2.0 because our builders can't handle it (and it's probably incompatible, too)
-gem 'git'
-gem 'json'
+gem 'versionomy', '~> 0.5.0'
+gem 'rake', '~> 13.0', '>= 13.0.1'
+gem 'rack', '~> 2.2', '>= 2.2.3'
+gem 'git', '~> 1.7'
+gem 'json', '~> 2.3', '>= 2.3.1'
 
 group(:build_site) do
-  gem 'jekyll', '3.0.1'
-  gem 'kramdown', '1.12.0'
-  gem 'vlad'
-  gem 'vlad-git'
+  gem 'jekyll', '~> 3.8' # See https://jekyllrb.com/docs/upgrading/3-to-4/ before going to '~> 4.1'
+  gem 'kramdown', '~> 1.17'
+  gem 'vlad', '~> 1.4'
+  gem 'vlad-git', '~> 2.1'
   gem 'listen', '~> 3.0.0' # Preserve ability to run on Ruby 2.0, since listen 3.1 requires Ruby ~> 2.2.
 end
 
 group(:generate_references) do
-  gem 'ronn'
-  gem 'yard'
-  gem 'rdoc'
-  gem 'rgen'
-  gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git', :tag => 'v2.3.0'
-  gem 'puppet'
-  gem 'nokogiri'
-  gem 'pragmatic_segmenter'
-  gem 'punkt-segmenter'
+  gem 'ronn', '~> 0.7'
+  gem 'yard', '~> 0.9'
+  gem 'rdoc', '~> 6.2'
+  gem 'rgen', '~> 0.8'
+  gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git', :tag => 'v2.4.0'
+  gem 'puppet', '~> 6'
+  gem 'nokogiri', '~> 1.10'
+  gem 'pragmatic_segmenter', '~> 0.3'
+  gem 'punkt-segmenter', '~> 0.9'
 end
 
 group(:unknown) do
-  gem 'maruku'
+  gem 'maruku', '~> 0.7'
   gem 'activerecord', '~>3'
 end
 

Gemfile.lock

@@ -0,0 +1,167 @@
+GIT
+  remote: https://github.com/puppetlabs/puppet-strings.git
+  revision: 8f11ae8b3577b07062c0cbd08b4396ca05fb16b0
+  tag: v2.4.0
+  specs:
+    puppet-strings (2.4.0)
+      rgen
+      yard (~> 0.9.5)
+
+PATH
+  remote: .
+  specs:
+    puppet_docs (0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.22.5)
+      activesupport (= 3.2.22.5)
+      builder (~> 3.0.0)
+    activerecord (3.2.22.5)
+      activemodel (= 3.2.22.5)
+      activesupport (= 3.2.22.5)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.22.5)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    arel (3.0.3)
+    blockenspiel (0.5.0)
+    builder (3.0.4)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.6)
+    deep_merge (1.2.1)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    facter (4.0.30)
+      hocon (~> 1.3)
+      thor (>= 1.0.1, < 2.0)
+    fast_gettext (1.8.0)
+    ffi (1.13.1)
+    forwardable-extended (2.6.0)
+    git (1.7.0)
+      rchardet (~> 1.8)
+    hiera (3.6.0)
+    hocon (1.3.1)
+    hpricot (0.8.6)
+    http_parser.rb (0.6.0)
+    httpclient (2.8.3)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.8.7)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    json (2.3.1)
+    kramdown (1.17.0)
+    liquid (4.0.3)
+    listen (3.0.8)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    locale (2.1.3)
+    maruku (0.7.3)
+    mercenary (0.3.6)
+    mini_portile2 (2.4.0)
+    multi_json (1.15.0)
+    mustache (1.1.1)
+    nokogiri (1.10.10)
+      mini_portile2 (~> 2.4.0)
+    open4 (1.3.4)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    pragmatic_segmenter (0.3.22)
+      unicode
+    public_suffix (4.0.5)
+    punkt-segmenter (0.9.1)
+      unicode_utils (>= 1.0.0)
+    puppet (6.17.0)
+      concurrent-ruby (~> 1.0)
+      deep_merge (~> 1.0)
+      facter (> 2.0.1, < 5)
+      fast_gettext (~> 1.1)
+      hiera (>= 3.2.1, < 4)
+      httpclient (~> 2.8)
+      locale (~> 2.1)
+      multi_json (~> 1.10)
+      puppet-resource_api (~> 1.5)
+      semantic_puppet (~> 1.0)
+    puppet-resource_api (1.8.13)
+      hocon (>= 1.0)
+    rack (2.2.3)
+    rake (13.0.1)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rchardet (1.8.0)
+    rdiscount (2.2.0.1)
+    rdoc (6.2.1)
+    rgen (0.8.2)
+    ronn (0.7.3)
+      hpricot (>= 0.8.2)
+      mustache (>= 0.7.0)
+      rdiscount (>= 1.5.8)
+    rouge (3.21.0)
+    safe_yaml (1.0.5)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    semantic_puppet (1.0.2)
+    thor (1.0.1)
+    tzinfo (0.3.57)
+    unicode (0.4.4.4)
+    unicode_utils (1.4.0)
+    versionomy (0.5.0)
+      blockenspiel (~> 0.5)
+    vlad (1.4.0)
+      open4
+      rake (>= 0.8.1)
+    vlad-git (2.1.0)
+    yard (0.9.25)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 3)
+  git (~> 1.7)
+  jekyll (~> 3.8)
+  json (~> 2.3, >= 2.3.1)
+  kramdown (~> 1.17)
+  listen (~> 3.0.0)
+  maruku (~> 0.7)
+  nokogiri (~> 1.10)
+  pragmatic_segmenter (~> 0.3)
+  punkt-segmenter (~> 0.9)
+  puppet (~> 6)
+  puppet-strings!
+  puppet_docs!
+  rack (~> 2.2, >= 2.2.3)
+  rake (~> 13.0, >= 13.0.1)
+  rdoc (~> 6.2)
+  rgen (~> 0.8)
+  ronn (~> 0.7)
+  versionomy (~> 0.5.0)
+  vlad (~> 1.4)
+  vlad-git (~> 2.1)
+  yard (~> 0.9)
+  

LICENSE

@@ -1,6 +1,6 @@
 The content in this documentation project is
 
-Copyright (c) 2009-2016 Puppet, Inc.
+Copyright (c) Puppet, Inc.
 
 Licensed under the Creative Commons 3.0
 with Attribution and Share Alike Clauses
@@ -15,11 +15,7 @@ OR COPYRIGHT LAW IS PROHIBITED.
 
 ==============================================
 
-The application to develop this content is
-
-Copyright (c) 2009-2017 Puppet, Inc.
-
-Based on Rails Guides:
+The application to develop this content is based on Rails Guides:
 
 Copyright (c) 2004-2009 David Heinemeier Hansson
 

README.markdown

@@ -4,18 +4,22 @@ Curated documentation for Puppet.
 
 ## Where is everything?
 
-This repo has been split into two distinct branches of documentation, archived and current. The master branch contains only documentation that is presently being generated into HTML and delivered to our Drupal integration. The archive branch contains older versions of documentation that are to be migrated to a new archive site.
+Most of our documentation has been moved out of this repository. This repo contains:
+  * Some of our older, unmaintained documentation, which is deprecated and may be removed from this repo without further notice. For archived docs for unmaintained, unsupported versions of Puppet, see the [Puppet docs archive](https://github.com/puppetlabs/docs-archive).
+  * Reference documentation generated from code. This reference documentation is then rendered into HTML and included in the Puppet docs website.
 
-Starting in Puppet 5.5, and continuing into current releases, we are migrating much of the Puppet documentation into DITA format in a CMS called easyDITA. When we have migrated a Markdown page in the docs to DITA, we delete it from here so that it's clear what page to update when changes come (and so that the old content isn't accidentally published). 
+As of Puppet 5.5, Puppet docs were migrated into the DITA XML format and have been maintained in a CMS. We removed each migrated page from this repository, so that the old content wasn't accidentally published.
 
-Starting in Facter 3.12, the Facter docs have been migrated to easyDITA (in the Puppet doc set), so updates to 3.12 (and later) should be made there instead of here. The generated core_facts.md file is still in github, but has moved to the puppet/x.y folder instead of facter/x.y.
+As of Facter 3.12, the Facter docs were migrated to DITA and organized as part of the Puppet doc set. Updates to 3.12 (and later) should be made in DITA, not in this repo. The generated `core_facts.md` file is still this repository, but has moved to the `puppet/x.y` folder instead of `facter/x.y`.
 
-## Contributions from the Puppet community are still very welcome.
+## Contributions from the Puppet community are welcome
 
-- If something in the documentation doesn't seem right, or if you think something important is missing, open a Jira ticket in the DOCUMENT project here: https://tickets.puppetlabs.com/projects/DOCUMENT/ Let us know the URL of the page, and describe the changes you think it needs.
-- Or email docs@puppet.com if you have questions about contributing to the documentation.
+If something in the documentation doesn't seem right, or if you think something important is missing, we want to hear from you! Please send us feedback in any of the following ways:
+* Use the feedback form on the relevant page to send us details of the issue.
+* Open a Jira ticket in the DOCUMENT project here: https://tickets.puppetlabs.com/projects/DOCUMENT/ Let us know the URL of the page, and describe the changes you think it needs.
+* Email `docs@puppet.com` if you have questions about contributing to the documentation.
 
 
 ## Copyright
 
-Copyright (c) 2009-2018 Puppet, Inc. See LICENSE for details.
+Copyright (c) 2009-2020 Puppet, Inc. See LICENSE for details.

README_WRITING.markdown

@@ -1 +1 @@
-If you've bookmarked or linked to this page as a source of information about contributing to Puppet documentation, please update it to point to [Contributing](https://docs.puppet.com/contribute.html)
+If you've bookmarked or linked to this page as a source of information about contributing to Puppet documentation, please update it to point to [Contributing](https://puppet.com/docs/puppet/latest/contributing.html)

Rakefile

@@ -19,9 +19,30 @@ VERSION_FILE = "#{OUTPUT_DIR}/VERSION.txt"
 @config_data = PuppetDocs::Config.new("#{SOURCE_DIR}/_config.yml")
 
 def jekyll(command = 'build', source = SOURCE_DIR, destination = OUTPUT_DIR, *args)
+
+  about_verbose_mode = <<-ABOUT_VERBOSE_MODE
+
+    -*-*-*-*-*-*-*-*-*-*-*-*-
+
+    To turn on verbose mode and logging,
+    $ export DEBUG_PUPPET_DOCS_RAKEFILE=1
+
+    To turn off,
+    $ unset DEBUG_PUPPET_DOCS_RAKEFILE
+
+    -*-*-*-*-*-*-*-*-*-*-*-*-
+
+  ABOUT_VERBOSE_MODE
+
+  puts about_verbose_mode
+
+  if ENV['DEBUG_PUPPET_DOCS_RAKEFILE']
+    verbose_mode = '--verbose | tee puppet-docs-build.log'
+  end
+
   amended_config = "#{SOURCE_DIR}/_config_amended.yml"
   File.write(amended_config, YAML.dump(@config_data))
-  system("bundle exec jekyll #{command} --source #{source} --destination #{destination} #{args.join(' ')} --config #{amended_config}")
+  system("set -x; bundle exec jekyll #{command} --source #{source} --destination #{destination} #{args.join(' ')} --config #{amended_config} #{verbose_mode}")
   FileUtils.rm(amended_config)
 end
 

lib/README.markdown

@@ -0,0 +1,57 @@
+# Configuring docs generation
+
+Curated documentation for Puppet and tools for generating a deployable copy
+of the docs site.
+
+> **NOTE:** These instructions are no longer relevant for generating most documentation
+published to puppet.com/docs, but are still useful for testing changes to content
+generated from Puppet codebases.
+
+Installation
+------------
+
+The tools and rake tasks for generating the puppet-docs site require Ruby 2.2.3 or greater.
+
+To install the documentation-generating code:
+
+1.  Clone the repository:
+
+        $ git clone git://github.com/puppetlabs/puppet-docs.git
+
+2.  Use your package manager to install rake, libxml2-dev, libxslt-dev, and pygments.
+    Package names may vary by platform; for example, using Macports, these packages could
+    be installed with:
+
+        $ sudo port -d install rb-rake libxml2 libxslt py-pygments
+
+    Make sure there is a `pygmentize` command available! If your package tools
+    install the pygmentize binary with a different name (like Macports does),
+    you must symlink it so Jekyll can find the command.
+
+3.  Install the Ruby dependencies:
+
+    The Puppet docs project uses Ruby Bundler to ensure that you have the correct dependencies
+    installed on your system and that the documents are being built with the correct versions
+    of needed binaries. To install the project's requirements:
+
+        $ sudo gem install bundler
+        $ cd puppet-docs
+        $ bundle install --path=vendor/bundle
+
+Building and viewing
+--------------------
+
+1.  Generate the documentation:
+
+        $ rake generate
+
+2.  Start a little server to view it at http://localhost:9292:
+
+        $ rake serve
+
+    (You can use `rake run` to combine these steps.)
+
+Copyright
+---------
+
+Copyright (c) 2009-2019 Puppet, Inc. See LICENSE for details.