Skip to content

WORKFLOW_reference.md

Latest commit

 

History

History
220 lines (147 loc) · 5.09 KB

WORKFLOW_reference.md

File metadata and controls

220 lines (147 loc) · 5.09 KB

Workflow for genrating reference

There are two generated refefences:

  1. from openfact
  2. from opnvox-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

CLI

CLI is rendered from man pages to markdown. Content is in the openvox repositoriy.

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 contnet 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 inhertited 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

  1. Rakefile

Rakefile

OpenFact

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
  1. executes ruby /lib/docs/generate.rb
  2. adds header data + preamble + data
  3. writes core_facts.md file
CLI
  1. runs bundle update in openfact
  2. runs bundle exec facter man
  3. uses PandDoc Ruby to convert man to markdown
  4. writs cli.md

OpenVox

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

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

  2. deletes face_base, indirection_base, cert applications 1.build index for all applications

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

  4. select from applications where data match

  5. 2 variables: header data and index_text

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

  7. write content to overview.md file

  8. for each command run build_manpage

  9. define a header

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

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

  12. write command file

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

typedoc script: /lib/puppet_references/quarantine/get_typedocs.rb typedoc template: /lib/puppet_references/puppet/type_template.erb typedoc preamble: lib/puppet_references/puppet/type_preamble.md

build_all:

get_type_json: execute typedoc script save json file

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)

build_unified_page:

set header (title, canonical, toc_levels, toc) sort attributes (namenvar first, ensure second) write type individual files

build page:

set header (title, canonical) sort attributes write type file

TypeStrings

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

template: functions_template.erb preamble: functions_preamble.md

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