chef/chef-web-docs chef/chef-web-docs

  • Stars
    star
    127
  • Rank 273,829 (Top 6 %)
  • Language
    HTML
  • License
    Other
  • Created over 8 years ago
  • Updated 5 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
chef/chef-web-docs
github

chef

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

All The Documentation

This GitHub Repository is the source for the Chef documentation published on docs.chef.io.

The https://github.com/chef/chef-web-docs repository contains:

  • Source code for the documentation theme
  • Markdown files for much of the Chef Infra Client content
  • Configuration files
  • Vendored files for documentation from other repositories that are presented on docs.chef.io.

This README.md covers information on building and previewing documentation. The House Style Guide and more detailed information about Hugo and our documentation tools are published in the documentation:

Distributed Documentation

The Chef documentation source is highly distributed and depends on Hugo modules to pull in documentation from other Chef repositories. The content from those repositories is vendored in chef-web-docs.

To make changes to the content in those repositories, submit pull requests to the appropriate repository. Do not submit pull requests to the vendored files in chef-web-docs. We will update those changes after they're merged or after a new version of a product is released.

GitHub Repositories with Documentation

The Fastest Way to Contribute

The fastest way to change the documentation is to edit a page on the GitHub website using the GitHub UI.

To perform edits using the GitHub UI, click on the [edit on GitHub] link at the top of the page that you want to edit. The link takes you to that topic's GitHub page. In GitHub, click on the pencil icon and make your changes. You can preview how they'll look right on the page ("Preview Changes" tab).

We also require contributors to include their DCO signoff in the comment section of every pull request, except for obvious fixes. You can add your DCO signoff to the comments by including Signed-off-by:, followed by your name and email address, like this:

Signed-off-by: Haris Shefu <[email protected]>

See our blog post for more information about the DCO and why we require it.

After you've added your DCO signoff, add a comment about your proposed change, then click on the "Propose file change" button at the bottom of the page and confirm your pull request. The CI system will do some checks and add a comment to your PR with the results.

The Chef Documentation Team can normally merge pull requests within seven days. We'll fix build errors before we merge, so you do not have to worry about passing all of the CI checks, but it might add an extra few days. The important part is submitting your change.

Local Development Environment

The Chef Documentation website is built using:

  • Hugo 0.104.3 or higher
  • Node 10.0.0 or higher
  • NPM 5.6.0 or higher
  • Go 1.12 or higher

To install Hugo, NPM, and Go on Windows and macOS:

  • On macOS run: brew install hugo node go
  • On Windows run: choco install hugo-extended nodejs golang

To install Hugo on Ubuntu, run:

  • apt install -y build-essential
  • snap install node --classic --channel=12
  • snap install hugo --channel=extended

Troubleshooting Your Development Environment

To clean your local development environment:

  • Run make clean to delete the sass files, javascript, and fonts. These will be rebuilt the next time you run make serve.

  • Run make clean_all to delete the node modules used to build this site in addition to the functions of make clean described above. Those node modules will be reinstalled the next time you run make serve.

Build and Preview the Docs

There are two ways to preview documentation:

  • Submit a PR and look at the Netlify preview.
  • Build the documentation locally.

Submit a PR and Look at the Netlify Preview

We have configured Netlify to generate deploy previews of pull requests to the chef-web-docs repository. Netlify will add a comment to the PR with a link to the deploy preview after it finishes building the preview.

Netlify will automatically build deploy previews for PRs from contributors who are members of the Chef GitHub organization. The Documentation Team can manually tell Netlify to build previews from contributors who are not members of the Chef GitHub organization.

Build and Preview the Docs Locally

Note that this repository consumes content from other repositories using Hugo modules. That content is stored in the _vendor directory. make serve uses the content in your local _vendor directory instead of from its source GitHub repository OR from a local copy of a repository.

Build and Preview the Docs from the Source Repositories

  • Run make serve_ignore_vendor

Some Chef documentation is stored in private repositories so this option is only available to Progress Chef employees.

Hugo Vendoring

Vendoring stores all of the module content from other repositories in the _vendor directory at the commit specified by the go.mod file. When Hugo builds the documentation, it will grab content from the _vendor directory instead of the original repository OR a local copy of a that repository. To see which commits the vendored files reference, see the _vendor/modules.txt file.

To vendor the modules in chef-web-docs, run hugo mod vendor.

To update the vendored modules, first update the Hugo module(s), then run hugo mod vendor.

To ignore the vendored files in a Hugo build, run make serve_ignore_vendor. This is the same as make serve except it adds the --ignoreVendor flag. This will build the documentation from the GitHub repositories or from a local copy of a repository if the go.mod file specifies pulling content from a local repository. (see above)

Update Hugo Modules

Hugo modules are pinned to a particular commit of the master branch in their repository. If you look in the go.mod and go.sum files, you'll notice that each repository specifies a git commit timestamp and SHA.

To update a particular repo, run:

hugo mod get github.com/chef/repo_to_update/subdirectory
hugo mod clean

Then vendor the documentation:

hugo mod vendor

For example, to update the chef-workstation repository:

hugo mod get github.com/chef/chef-workstation/docs-chef-io
hugo mod clean
hugo mod vendor

This will update that repository to the most recent commit.

You can also update a module to a commit version number. For example:

hugo mod get github.com/chef/chef-workstation/docs-chef-io@20.6.62
hugo mod clean
hugo mod vendor

And you can update a module to a Git commit. For example:

hugo mod get github.com/chef/chef-workstation/docs-chef-io@0ad84dd5fa8
hugo mod clean
hugo mod vendor

To update all Hugo modules at the same time, run:

hugo mod get -u
hugo mod clean
hugo mod vendor

The hugo mod clean command removes references to commits in the go.mod and go.sum files that are no longer relevant.

See Hugo's documentation for additional information about updating Hugo Modules.

What if Hugo Does not Want to Update a Module

Sometimes Hugo and Git can be a bit difficult and will not update a module cleanly or will leave references to older commits of a module in the go.sum file.

If you get an error indicating that a Git cannot find a repository that's already been added as a module, try restarting your computer.

If you are still having trouble, try rebuilding the go.mod and go.sum files:

  1. Delete the go.mod and go.sum files.
  2. Re-initialize the Hugo modules, hugo mod init github.com/chef/chef-web-docs This will generate a new, blank go.mod file.
  3. Update the references to the other GitHub repositories, hugo mod get -u.
  4. The previous step will update all modules to the latest commit of their source repositories. If you do not want that, look at the git history of those files and manually edit the go.mod and go.sum files to keep the older commits for the modules that you do not want to update.
  5. Run hugo mod tidy. This probably will not do anything on newly initialized go.mod and go.sum files, but it cannot hurt either.
  6. Vendor the modules in chef-web-docs, hugo mod vendor.

Release Notes

Release notes are added to release notes pages using Hugo's resource.getRemote function and content from https://omnitruck.chef and https://packages.chef.io.

Chef Automate release versions, release dates, and links to release note Markdown files come from https://packages.chef.io/releases/current/automate.json.

Release versions for Chef habitat come from https://api.github.com/repos/habitat-sh/habitat/releases.

Release versions for Chef InSpec Cloud resources comes from _vendor/github.com/inspec/inspec-<PLATFORM>/docs-chef-io/assets/release-notes/inspec-<PLATFORM>/release-dates.json.

Release versions for all other Chef products come from https://omnitruck.chef.io/stable/<PRODUCT>/versions/all.

Each release note page comes from a Markdown file from https://packages.chef.io/release-notes/<PRODUCT>/<VERSION>.md.

If a release note Markdown file is not returned from packages.chef.io, the release note for that version will show the text, "This release does not have any release notes."

Previewing Release Notes Locally

Release note pages are only generated in the production environment. Running make serve will not build any of the content in the release note pages.

Run make production to build and preview the release notes.

Run make clean_all to purge locally cached release note files.

Adding Release Note Pages

To add a release notes page to chef-web-docs, add the following to a Markdown page:

release_notes = "<CHEF_PRODUCT>"
product = "<CHEF_PRODUCT>"
layout = "release_notes"
toc_layout = "release_notes_toc"

The <CHEF_PRODUCT> value comes from the Product Key in the Product Matrix.

Any content included in the release notes Markdown file will be included at the top of the page and the release notes will be appended below.

Documentation Snapshots

The previous scoped doc sets that were found on docs.chef.io are no longer available in this repo. Instead, those doc sets are located at Chef Docs Archive. The index page on the docs archive site provides links to them. The doc sets retain their unique left nav and can be used to view content at a particular point in time for a given release. In the future, snapshots will be added for major releases of products/projects or for products/projects/components that are no longer supported.

Archive of pre-2016 commit history

The commit history of this repo before February 12, 2016 has been archived to the chef-web-docs-2016 repo to save space. No changes to the archive repo will be merged; it is just for historical purposes.

Sending Feedback

We love getting feedback. You can use:

More Repositories

1

chef

Chef Infra, a powerful automation platform that transforms infrastructure into code automating how infrastructure is configured, deployed and managed across any environment, at any scale
Ruby
7,442
star
2

bento

Packer templates for building minimal Vagrant baseboxes for multiple platforms
HCL
4,197
star
3

omnibus

Easily create full-stack installers for your project across a variety of platforms.
Ruby
1,269
star
4

ohai

Ohai profiles your system and emits JSON
Ruby
672
star
5

chef-zero

Simple, easy-run, fast-start in-memory Chef server for testing and solo purposes
Ruby
534
star
6

chef-vault

Securely manage passwords, certs, and other secrets in Chef
Ruby
407
star
7

knife-ec2

Chef knife plug-in for AWS EC2
Ruby
403
star
8

chef-server

Chef Infra Server is a hub for configuration data; storing cookbooks, node policies and metadata of managed nodes.
Erlang
279
star
9

automate

Chef Automate provides a full suite of enterprise capabilities for maintaining continuous visibility into application, infrastructure, and security automation.
Go
220
star
10

supermarket

Chef's community platform
Ruby
210
star
11

knife-vsphere

Chef knife plug-in for VMware vSphere
Ruby
201
star
12

knife-windows

Plugin for Chef's knife tool for working with Windows nodes
Ruby
151
star
13

mixlib-shellout

mixin library for subprocess management, output collection
Ruby
132
star
14

omnibus-software

Open Source Software for use in Omnibus built packages
Ruby
132
star
15

chef-workstation

Chef Workstation gives you everything you need to get started with Chef, so you can automate how you audit, configure, and manage applications end environments.
Go
131
star
16

mixlib-cli

A mixin for creating command line applications - gives an easy DSL for argument specification and processing
Ruby
123
star
17

knife-openstack

Chef Infra knife plug-in for OpenStack
Ruby
120
star
18

cookstyle

A linting tool that helps you to write better Chef Infra cookbooks and InSpec profiles by detecting and automatically correcting style, syntax, and logic mistakes in your code.
Ruby
107
star
19

chef-oss-practices

Documentation and Practices for Open Source Development at Chef
Ruby
81
star
20

os_release

A repo containing the /etc/os-release file from various Linux distros
73
star
21

knife-azure

Chef knife plug-in for Microsoft Azure
Ruby
72
star
22

artifactory-client

A simple, lightweight Ruby client for interacting with the Artifactory API.
Ruby
68
star
23

knife-google

Chef knife plug-in for Google Compute
Ruby
67
star
24

win32-service

A Ruby library that allows users to inspect, control or create services on MS Windows
Ruby
65
star
25

mixer

Mix in functions from other modules
Erlang
64
star
26

concrete

Concrete enhances your rebar based Erlang project by providing a common Makefile wrapper, a dialyzer make target that caches PLT analysis of your project's dependencies, and a mechanism to specify development only dependencies.
Erlang
55
star
27

mixlib-config

A simple class based Config mechanism, similar to the one found in Chef
Ruby
51
star
28

sqerl

General purpose RDBMS abstraction layer
Erlang
42
star
29

vscode-chef

Chef Infra Extension for Visual Studio Code
TypeScript
40
star
30

cheffish

Resources and tools for testing and interacting with Chef and Chef Server.
Ruby
39
star
31

knife-tidy

Report on stale Chef Server nodes/cookbooks, clean those up and additionally clean data integrity issues from a knife-ec-backup object based backup!
Ruby
36
star
32

homebrew-chef

A homebrew tap for ChefDK, Workstation, and InSpec
Ruby
36
star
33

mixlib-log

A simple class based Log mechanism, similar to Merb and Chef, that you can mix in to your project.
Ruby
34
star
34

effortless

Automated best practices for Chef Infra and Chef InSpec
Shell
33
star
35

knife-ec-backup

Backup and restore Chef Infra Server in a repository-compatible format
Ruby
31
star
36

chef-load

chef-load - a tool for simulating load on a Chef Infra Server and/or a Chef Automate server
Roff
31
star
37

mini_s3

Minimal AWS S3 client for Erlang
Erlang
28
star
38

okta_aws

Tool for accessing the AWS API for an account you normally access via okta
Python
27
star
39

omnitruck

Web service to automate the release of Omnibus artifacts
Ruby
26
star
40

dep-selector

Fast Dependency Solver for Ruby using Gecode
Ruby
25
star
41

win32-process

A Ruby library that adds or redefines several methods for the Process module
Ruby
25
star
42

erlang-bcrypt

This is an unmaintained fork of smarkets/erlang-bcrypt. Please use that repository instead.
C
25
star
43

kitchen-vcenter

A test-kitchen driver for vCenter REST API
Ruby
25
star
44

omnibus-ctl

Provides service control for omnibus packages
Ruby
23
star
45

mixlib-authentication

AuthN signing and verification. Appears in both the client and server
Ruby
22
star
46

knife-cloud

Library for Chef knife cloud plugins
Ruby
18
star
47

win32-taskscheduler

A Ruby interface for the task scheduler on MS Windows
Ruby
17
star
48

mixlib-versioning

General purpose Ruby library that allows you to parse, compare, and manipulate version strings in multiple formats.
Ruby
17
star
49

win32-eventlog

The win32-eventlog library provides a Ruby interface for reading from and writing to the Windows Event Log
Ruby
17
star
50

chefstyle

Version Pinned RuboCop with Chef approved Cop list for linting software - NOT FOR COOKBOOKS
Ruby
15
star
51

chef-cli

The 'chef' command line tool included in Chef Workstation
Ruby
14
star
52

win32-file

Extra methods, and redefined methods, for the File class on MS Windows
Ruby
14
star
53

appbundler

Generate locked binstubs for ruby applications
Ruby
14
star
54

stats_hero

General purpose stats collection
Erlang
13
star
55

knife-vrealize

Plugin for Chef's knife tool to interact with VMware vRealize products
Ruby
13
star
56

anka-buildkite-plugin

Run Buildkite steps inside Veertu Anka Virtual Machines
Shell
13
star
57

chef-apply

The ad-hoc execution tool for the Chef ecosystem.
Ruby
13
star
58

wmi-lite

Lightweight, low-dependency wrapper for basic WMI functionality on Windows.
Ruby
13
star
59

mixlib-install

A library for interacting with Chef Software Inc's software distribution systems.
Ruby
12
star
60

ffi-libarchive

A Ruby FFI binding to libarchive.
Ruby
12
star
61

chef_authn

Erlang API request authentication signing and verification for Chef
Erlang
11
star
62

fixie

Low level manipulation tool for chef in sql
Ruby
10
star
63

ffi-yajl

Ruby FFI gem wrapper around yajl2 library
Ruby
10
star
64

dep-selector-libgecode

Bundled Gecode Libraries for dep-selector
Ruby
10
star
65

win32-certstore

Ruby library for accessing the certificate store on Windows
Ruby
10
star
66

corefoundation

FFI based Ruby bindings for the CoreFoundation frameworks
Ruby
10
star
67

chef-workstation-app

The Chef Workstation desktop application.
TypeScript
10
star
68

knife-vcenter

Chef knife plug-in for VMware REST API
Ruby
9
star
69

win32-security

A Ruby interface for security aspects of MS Windows
Ruby
9
star
70

win32-dir

A series of constants, and extra or redefined methods, for the Dir class on Windows
Ruby
8
star
71

chef_backup

A library to backup an Chef server
Ruby
8
star
72

chef-vault-testfixtures

provides an RSpec shared context for testing Chef cookbooks that use chef-vault
Ruby
7
star
73

opscoderl_httpc

Opscode helper application for being an HTTP client
Erlang
7
star
74

license-acceptance

Chef Software libraries for accepting usage license
Ruby
7
star
75

rubydistros

Dockerfiles for Ruby on various Linux distros
Dockerfile
7
star
76

win32-mmap

A Ruby interface for memory mapped files on MS Windows
Ruby
7
star
77

win32-event

A Ruby interface to Event objects on MS Windows
Ruby
6
star
78

chef-analyze

A CLI to analyze artifacts from a Chef Infra Server
Go
6
star
79

license_scout

Discovers license information of the dependencies of a project.
Ruby
6
star
80

.github

.github files that are inherited by all org repos unless specifically included in a repo
6
star
81

cookbook-omnifetch

Fetch Chef Cookbooks from Various Sources to a Local Cache
Ruby
6
star
82

github-workflows

Github Actions Workflows
5
star
83

win32-ipc

A Ruby abstract base class for synchronization objects on MS Windows
Ruby
5
star
84

appbundle-updater

A little help when you want to update an appbundled project inside of a Chef/ChefDK omnibus package
Ruby
5
star
85

ci-studio-common

Shared helpers for use inside CIs (like Travis) and a Habitat Studio
Go
5
star
86

omnibus-toolchain

Omnibus packaging for Omnibus toolchain
Ruby
5
star
87

chef-web-core

Shared resources for Chef web properties
Ruby
5
star
88

gatherlogs-reporter

Inspec profiles for examining gatherlog output from chef-products for support.
Ruby
5
star
89

architecture-center

Ruby
5
star
90

chocolatey-packages

PowerShell
4
star
91

compliance-workshop-environment

Ruby
4
star
92

inspec-extra-resources

Ruby
4
star
93

folsom_graphite

Send data from folsom automatically to graphite
Erlang
4
star
94

cookstylist

Cookstyle GitHub app
Ruby
4
star
95

chef-powershell-shim

.NET 4.0/COM wrapper around PowerShell host
Ruby
4
star
96

automate-liveness-agent

Agent that sends "keep alive" messages to Chef Automate
Ruby
4
star
97

community_cookbook_releaser

A simple script to aid in version bumps and changelog generation for Chef managed community cookbooks
Ruby
4
star
98

habitat_exporter

Go
4
star
99

mixlib-archive

A very simple gem to create and extract archives.
Ruby
4
star
100

win32-mutex

A Ruby interface for mutexes on MS Windows
Ruby
3
star