Skip to content

WORKFLOW_reference.md

Latest commit

 

History

History
239 lines (160 loc) · 5.57 KB

WORKFLOW_reference.md

File metadata and controls

239 lines (160 loc) · 5.57 KB

Workflow for generating reference

There are two generated references:

  1. from openfact
  2. from openvox-agent

OpenFact

From OpenFact we collect:

  1. CLI
  2. Core Facts

OpenVox Agent

From OpenVox agent we fetch

  1. bundled types and providers
  2. bundled functions

Changing content

OpenFact Content

CLI

CLI is rendered from man pages to markdown. Content is in the openfact repository.

Additional content is added via a preamble: lib/puppet_references/facter/facter_cli_preamble.md

Core Facts

Core Facts are rendered using a script, which is part of the openfact repo (lib/docs/generate.rb)

Additional content is added via a preamble file: lib/puppet_references/facter/core_facts_preamble.md

OpenVox

OpenVox autogenerated documentation is rendered differently.

Man

Rendering takes place in lib/puppet_references/puppet/man.rb Line 78 ff

PuppetDoc

Completely rendered using puppet doc command from openvox repo documentation

Type

Type uses a preamble and a template:

  • lib/puppet_references/puppet/type_preamble.md and
  • lib/puppet_references/puppet/type_template.erb

TypeStrings

TypeStrings is inherited from Type.

Content is rendered by running puppet strings generate. Additional content is added in lib/puppet_references/puppet/type_strings.rb

Functions

Functions use a preamble and a template:

  • lib/puppet_references/puppet/functions_preamble.md and
  • lib/puppet_references/puppet/functions_template.erb

Workflow

This is a summarized analysis of the references generation process.

Rakefile

The rakefile has three rake tasks:

  • references - Prints out usage of the other ones
  • references:openfact
  • references:openvox

Each reference source is cloned into vendor/ directory.

GitHub URL is located in lib/puppet_references/repo.rb

OpenFact Workflow

PuppetReferences.build_facter_references(ENV.fetch('VERSION', nil))

build_facter_references

Building references

references = [
  PuppetReferences::Facter::CoreFacts,
  PuppetReferences::Facter::FacterCli
]

Repo action

repo = PuppetReferences::Repo.new('openfact', FACTER_DIR)
real_commit = repo.checkout(commit)
repo.update_bundle
  1. clone openfact repo into a local dir
  2. switches to provided version
  3. update all tags (fetch)
  4. runs bundle install
build_from_list_of_classes(references, real_commit)
Core Facts Workflow
  1. executes ruby <openfact>/lib/docs/generate.rb
  2. adds header data + preamble + data
  3. writes core_facts.md file
CLI Workflow
  1. runs bundle update in openfact
  2. runs bundle exec facter man
  3. uses Pandoc Ruby to convert man to markdown
  4. writes cli.md

OpenVox Workflow

PuppetReferences.build_puppet_references(ENV.fetch('VERSION', nil))

build puppet reference
references = [
      PuppetReferences::Puppet::Man,
      PuppetReferences::Puppet::PuppetDoc,
      PuppetReferences::Puppet::Type,
      PuppetReferences::Puppet::TypeStrings,
      PuppetReferences::Puppet::Functions,
    ]
  1. Reads config - can be removed
  2. Clones repo
  3. switch to version
  4. run bundle install
  5. build_from_list_of_classes (build_all)
Man Workflow

  1. reads all files in openvox-agent/lib/puppet/application/*.rb

  2. deletes face_base, indirection_base, cert applications

  3. build index for all applications

    1. has data with categories: core, occasional and weird

  4. select from applications where data match

  5. 2 variables: header data and index_text

    1. within index_text, add the markdown files mentioned in data first core, then occasional, then weird

  6. write content to overview.md file

  7. for each command run build_manpage

  8. define a header

  9. read command from openvox-agent/man/man/command.8

  10. calls PandDoc.ruby to convert from man to markdown, adding gsub methods on converted content

  11. write command file

PuppetDoc Workflow
  1. calls build_reference
  2. calls puppet doc command
  3. calls clean_configuration_reference
    1. replaces fqdn with fixed string
  4. sets header data
  5. writes each reference.md file
Type Workflow

typedoc script: <openvox-docs repo>/lib/puppet_references/quarantine/get_typedocs.rb typedoc template: <openvox-docs repo>/lib/puppet_references/puppet/type_template.erb typedoc preamble: <openvox-docs repo>lib/puppet_references/puppet/type_preamble.md

build_all:

  1. get_type_json: execute typedoc script

  2. save json file

  3. build_index (type_data.keys.sort):

  • header_data (title & canonical)
  • skip component and wiki
  • read all md files from type_data
  • add header (autogenerated) see lib/puppet_references/util.rb
  • write file (puppet/types/overview.md)
  1. build_unified_page:
  • set header (title, canonical, toc_levels, toc)
  • sort attributes (namenvar first, ensure second)
  • write type individual files
  1. build page:
  • set header (title, canonical)
  • sort attributes
  • write type file
TypeStrings Workflow

output dir: puppet/types_strings

same as type, but different get_type_json

  • PuppetReferences::Puppet::Strings.new

  • read all filenames in lib/puppet/**/*.rb

  • run bundle exec puppet strings generate --format json --out string.json filenames.join(' ')

  • read strings.json file

  • iterate over content['resource_type']

  • build new structure and content lib/puppet_references/puppet/type_strings.rb THIS IS THE IMPORTANT file

  • This has the knowledge on the output and renders the new md

Functions Workflow

template: functions_template.erb preamble: functions_preamble.md

  • uses PuppetReferences::Puppet::Strings.new
  • sets header
  • render template, add header
  • write file