forked from puppetlabs/bolt
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
(puppetlabsGH-2078) Add Bolt guide pages
This adds a new CLI command and PowerShell cmdlet which display information about various Bolt topics. The guides are read from text files that are saved in the `guides` directory, and are only loaded when a specific guide is being requested. To show a list of available guides: - **Unix shell command** ``` $ bolt guide ``` - **PowerShell cmdlet** ``` Get-Help about_bolt_* ``` To view the guide for a specific topic: - **Unix shell command** ``` $ bolt guide inventory ``` - **PowerShell cmdlet** ``` Get-Help about_bolt_inventory ``` This also adds an analytics event for both known guides and unknown guides. This allows Bolt to collect data about which guides users are viewing and which guides users may expect to be available. !feature * **View information about Bolt concepts and features from the CLI** ([puppetlabs#2078](puppetlabs#2078)) Bolt can now display information about various Bolt features and concepts with the new CLI command `bolt guide`.
- Loading branch information
Showing
16 changed files
with
364 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
# Topic guides | ||
|
||
Topic guides are concise descriptions of Bolt's features and concepts with links | ||
to relevant documentation. They act as a reference for users who are looking to | ||
better understand Bolt's features and concepts and quickly get to the | ||
information they are looking for. | ||
|
||
## Adding new topic guides | ||
|
||
To add a new topic guide, create a text file with the name `<topic>.txt` in this | ||
directory. Topics should be a single word containing only lowercase letters. The | ||
format for a guide should follow the same format as existing guides. | ||
|
||
## Adding guides to Bolt packages | ||
|
||
During the packaging process, Bolt will typically include all guides in this | ||
directory automatically. However, an extra step is required when adding new | ||
guides to ensure they are added to the Bolt PowerShell module when building the | ||
Windows package. | ||
|
||
To add a guide to the Bolt PowerShell module, you will need to add the file as a | ||
WiX component in `bolt-vanagon`, the tool used to build Bolt packages. To add a | ||
component, modify the following XML and add it to [this | ||
file](https://github.com/puppetlabs/bolt-vanagon/blob/main/resources/windows/wix/powershell.wxs.erb): | ||
|
||
```xml | ||
<Component | ||
Id="about_bolt_<TOPIC>.help.txt" | ||
Directory="PowerShellBoltModuleHelpDir" | ||
Guid="<GUID>"> | ||
<File | ||
Id="about_bolt_<TOPIC>.help.txt" | ||
Source="$(var.AppSourcePath)\share\PowerShell\Modules\PuppetBolt\en-US\about_bolt_<TOPIC>.help.txt" | ||
KeyPath="yes" /> | ||
</Component> | ||
``` | ||
|
||
> **Note:** Replace `<TOPIC>` with the name of the new topic and `<GUID>` with a | ||
> Globally Unique Identifier (GUID). You can generate a GUID in PowerShell using | ||
> the `Get-Guid` cmdlet. | ||
Once you have modified this file, open a [pull request against | ||
`bolt-vanagon`](https://github.com/puppetlabs/bolt-vanagon/pulls). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
TOPIC | ||
inventory | ||
|
||
DESCRIPTION | ||
The inventory describes the targets that you run Bolt commands on, along | ||
with any data and configuration for the targets. Targets in an inventory can | ||
belong to one or more groups, allowing you to share data and configuration | ||
across multiple targets and to specify multiple targets for your Bolt | ||
commands without the need to list each target individually. | ||
|
||
In most cases, Bolt loads the inventory from an inventory file in your Bolt | ||
project. The inventory file is a YAML file named 'inventory.yaml'. Because | ||
Bolt loads the inventory file from a Bolt project, you must have an existing | ||
project configuration file named 'bolt-project.yaml' alongside the inventory | ||
file. | ||
|
||
DOCUMENTATION | ||
https://pup.pt/bolt-inventory | ||
https://pup.pt/bolt-inventory-reference |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
TOPIC | ||
project | ||
|
||
DESCRIPTION | ||
A Bolt project is a directory that serves as the launching point for Bolt | ||
and allows you to create a shareable orchestration application. Projects | ||
typically include a project configuration file, an inventory file, and any | ||
content you use in your project workflow, such as tasks and plans. | ||
|
||
When you run Bolt, it runs in the context of a project. If the directory you | ||
run Bolt from is not a project, Bolt attempts to find a project by | ||
traversing the parent directories. If Bolt is unable to find a project, it | ||
runs from the default project, located at '~/.puppetlabs/bolt'. | ||
|
||
A directory is only considered a Bolt project when it has a project | ||
configuration file named 'bolt-project.yaml'. Bolt doesn't load project data | ||
and content, including inventory files, unless the data and content are part | ||
of a project. | ||
|
||
DOCUMENTATION | ||
https://pup.pt/bolt-projects | ||
https://pup.pt/bolt-project-reference |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.