iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update steps for generating the remote plugin docs.zip file (#10846) 

* Update steps for generating the remote plugin docs.zip file

* Update a few typos

* Fix tabbing issue
This commit is contained in:
Wilken Rivera 2021-03-30 17:12:28 -04:00 committed by GitHub
parent 03d79a2c39
commit f6dbc3e78a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
website/content/docs/plugins/creation/index.mdx
View File

@ -230,100 +230,62 @@ to install a plugin using `packer init`, see the
`packer init` allows users to require and install remote Packer plugins, those not bundled with Packer core, that have been published to GitHub automatically.
To help with the discovery of remote Packer plugins on GitHub, plugins maintainers can choose to register plugin documentation for each component directly on the [Packer Documentation Page](https://packer.io/docs).
The registration process requires the creation of a `.docs-artifacts` directory and a sidebar navigation file `docs-nav.json` for each of the plugin
components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/tree/main/.docs-artifacts).
The registration process requires the creation of a `docs.zip` file archive containing the `.mdx` files for each of the plugin components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/releases/latest).
Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/packer), which the needed configuration pulling in the remote documentation.
Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/packer), with the needed configuration for pulling in the remote documentation.
Remote plugins will have their components listed under the respected types (i.e builders, provisioners, etc) using the names specified in the remote block configuration, and labeled with their respective [tier and namespace](/docs/plugins#tiers-and-namespaces).
To register a plugin follow one of the following setups
<Tabs>
<Tab heading="Registering Using GitHub Actions">
<Tab heading="Generating docs.zip on plugin release">
Documentation for a plugin is maintained within the `docs` directory and served on GitHub.
A GitHub workflow has been added to [packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs) that
can be used generate a documentation structure that can be consumed remotely by https://packer.io. See the full workflow at [generated-docs-artifacts.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.github/workflows/generate-docs-artifacts.yml)
To include plugin docs on Packer.io a global pre-hook has been added to the main scaffolding [.goreleaser.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/42e5b0b1e575879b0477cb6d4291e027f4d92f85/.goreleaser.yml#L10) file, that if uncommented will generate and include a docs.zip file as part of the plugin release.
The GitHub workflow will automatically create the `.docs-artifacts` directory with the generated sidebar navigation file, and open a new pull-request against the default configured branch to be merged by the maintainer.
The `docs.zip` file will contain all of the `.mdx` files under the plugins root `docs/` directory that can be consumed remotely by Packer.io.
By default the workflow is configured to trigger on the creation of tags beginning with `'v*` to ensure that documentation gets updated for each release. Updates to the plugin documentation will get pulled in at the time of the next Packer website deployment.
Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs.
After merging the generated files to the default branch for the plugin repository.
Open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs.
This is done by adding the block below for the respective plugin to the file [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
This is done by adding the block below for the respective plugin to the file [website/data/docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
```json
{
"title": "Docker",
"path": "docker",
"repo": "hashicorp/packer-plugin-docker",
"title": "Scaffolding",
"path": "scaffolding",
"repo": "hashicorp/packer-plugin-scaffolding",
"version": "latest"
}
```
#### Required fields
`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions)
`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https
`repo`: The full name of the GitHub repository (i.e org/repo-name)
#### Optional fields
`branch`: The name of the default branch of the repository. Defaults to main.
`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`.
If a plugin maintainer wishes to only include a specific version of released docs then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to "latest".
</Tab>
<Tab heading="Registering Manually">
<Tab heading="Manually generating docs.zip">
The documentation structure needed for registering a plugin's documentation can be generated manually, but it is
encouraged to use the action on release events so that documentation stays up to date.
The documentation structure needed for Packer.io can be generated manually, by creating a zip file called `docs.zip` of the docs directory and included in the plugin release.
If your local development environment has a supported version (v10.0.0+) of [node](https://nodejs.org/en/) and a
supported version (>=5.2.0) [npm](https://www.npmjs.com/) installed, in the plugin root directory, you can run:
```shell-session
> npx -p @hashicorp/packer-docs-artifacts generate
```/bin/bash
[[ -d docs/ ]] && zip -r docs.zip docs/
```
The generated files will be placed under `PLUGIN_ROOT/.doc-artifacts`; this directory contains all the docs
and respective navigation information needed for including the plugin docs under [packer.io/docs/](https://packer.io/docs).
Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs.
After merging the generated files to the default branch for the plugin repository.
Open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs.
This is done by adding the block below for the respective plugin to the file [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
This is done by adding the block below for the respective plugin to the file [website/data/docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
```json
{
"title": "Docker",
"path": "docker",
"repo": "hashicorp/packer-plugin-docker",
"title": "Scaffolding",
"path": "scaffolding",
"repo": "hashicorp/packer-plugin-scaffolding",
"version": "latest"
}
```
#### Required fields
`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions)
`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https
`repo`: The full name of the GitHub repository (i.e org/repo-name)
#### Optional fields
`branch`: The name of the default branch of the repository. Defaults to main.
`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`.
If a plugin maintainer wishes to only include a specific version of released docs then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to "latest".
</Tab>
</Tabs>