Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-11-25 06:00:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

Clean up docs previews

Browse source 
Signed-off-by: IanMadd <imaddaus@chef.io>
This commit is contained in:
IanMadd 2020-12-10 18:02:52 -08:00
parent 567c8d3cf3
commit a9a41240b6
9 changed files with 54 additions and 588 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.gitmodules vendored
View file

@ -1,3 +0,0 @@
[submodule "docs-chef-io/chef-web-docs"]
path = docs-chef-io/chef-web-docs
url = https://github.com/chef/chef-web-docs

33
docs-chef-io/.gitignore vendored
View file

@ -1,35 +1,4 @@
# See http://help.github.com/ignore-files/ for more about ignoring files.
#
# If you find yourself ignoring temporary files generated by your text editor
# or operating system, you probably want to add a global ignore instead:
# git config --global core.excludesfile ~/.gitignore_global
.DS_Store
# ignore doctree files in translation folders
*.doctree
*.pickle
public/
/resources/
**/.sass-cache
**/.sass-cache/*
*.css.map
*.css_t.map
/.delivery/cli.toml
/.vscode
/.venv
*.*~
*~
TAGS
results/
static/fonts/fontawesome
node_modules
vendor
chef-web-docs/

49
docs-chef-io/Makefile
View file

@ -2,41 +2,24 @@
# so we have to override the default shell here
SHELL=bash
assets:
git submodule update --init --recursive
git submodule foreach git pull origin master
git submodule foreach git reset --hard
pushd chef-web-docs/themes/docs-new && make assets && popd
preview_netlify: chef_web_docs
cp -R content/* chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io/content
cp -R static/* chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io/static
pushd chef-web-docs && make assets; hugo --gc --minify --buildFuture && popd
clean:
pushd chef-web-docs/themes/docs-new && make clean && popd
rm -rf chef-web-docs/resources/
serve: chef_web_docs
echo "replace github.com/inspec/inspec/docs-chef-io => ../" >> chef-web-docs/go.mod
pushd chef-web-docs && make assets; hugo server --buildDrafts --buildFuture --noHTTPCache --ignoreVendorPaths "github.com/inspec/inspec/**" && popd
chef_web_docs:
if [ -d "chef-web-docs/" ]; then \
pushd chef-web-docs && git reset HEAD --hard; git pull origin master && popd; \
else \
git clone https://github.com/chef/chef-web-docs.git; \
fi
clean_all:
pushd chef-web-docs/themes/docs-new && make clean_all && popd
rm -rf chef-web-docs/resources/
rm -rf chef-web-docs/results/
pushd chef-web-docs && make clean_all && popd
preview_netlify: chef_web_docs_submodule
pushd chef-web-docs && make assets; hugo --buildFuture --gc --minify --enableGitInfo && popd
chef_web_docs_submodule:
git submodule update --init --recursive
git submodule foreach git pull origin master
git submodule foreach git reset --hard
cp -R content/* chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io/content
cp -R static/images/* chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io/static/images
cp -R layouts/* chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io/layouts
reset_chef_web_docs:
git submodule foreach git reset --hard
git submodule foreach git clean -f -d
update_chef_web_docs:
git submodule update --remote --merge chef-web-docs
serve: assets
hugo server --buildDrafts --buildFuture --noHTTPCache
lint: assets
lint:
hugo -D

334
docs-chef-io/README.md
View file

@ -1,16 +1,13 @@
# Chef InSpec Documentation
This is the home of the Chef InSpec documentation. This documentation provides
an introduction to this mechanism and shows how to write custom tests.
The goal of this folder is for any community member to clone these docs, make the
changes, check if they are valid, and contribute to the project.
This is the home of the InSpec Documentation that is deployed on
https://docs.chef.io/inspec/ using Hugo modules.
## The Fastest Way to Contribute
There are two steps to updating the Chef InSpec documentation:
1. Update the documentation in the inspec/inspec repository.
1. Update the documentation in the `inspec/inspec` repository.
1. Update the InSpec repository module in chef-web-docs
### Update Content in `inspec/inspec`
@ -45,40 +42,17 @@ few days. The important part is submitting your change.
### Update the InSpec Repository Module In `chef/chef-web-docs`
We use [Hugo modules](https://gohugo.io/hugo-modules/) and [vendoring](https://gohugo.io/hugo-modules/use-modules/#vendor-your-modules)
to build Chef's documentation from multiple repositories. The Hugo modules are
pinned to commits in each repository, and the documentation files from those
repositories and commits are vendored in `chef/chef-web-docs`. When the documentation
is updated in a repository, those changes won't appear in docs.chef.io until the
Hugo modules are updated to the new commit and the vendored files are updated.
We use [Hugo modules](https://gohugo.io/hugo-modules/) to build Chef's documentation
from multiple repositories. Expeditor will submit a pull request that updates the documentation
in `chef/chef-web-docs` the next time InSpec is promoted.
We use Expeditor to submit a pull request to `chef/chef-web-docs` when Chef InSpec
is promoted to stable.
To update the Hugo module for documentation in `inspec/inspec`:
1. Make sure your documentation changes are merged into master in `inspec/inspec/docs-chef-io`.
1. Wait for Expeditor to submit a PR to `chef/chef-web-docs` after Chef InSpec is promoted to stable.
If you need to manually update the Chef InSpec documentation, you can contact your
friendly local Docs Team who will update the Automate Hugo module for you.
Or, for the adventurous:
1. Make sure your documentation changes are merged into master in `inspec/inspec`.
1. On a local clone of `chef/chef-web-docs` run:
1. `hugo mod get github.com/inspec/inspec/docs-chef-io`
1. `hugo mod tidy`
1. `hugo mod vendor`
1. Submit a pull request to `chef/chef-web-docs`.
This will updated the InSpec vendored files in `chef-web-docs/_vendor/github.com/inspec/inspec/docs-chef-io`,
and update the commits in the go.mod and go.sum files in chef-web-docs.
The Docs Team can also update the InSpec documentation if changes need to be made
before the next promotion.
## Local Development Environment
We use [Hugo](https://gohugo.io/), [Go](https://golang.org/), and[NPM](https://www.npmjs.com/)
to build the Chef Documentation website. You will need Hugo 0.61 or higher
to build the Chef Documentation website. You will need Hugo 0.78.1 or higher
installed and running to build and view our documentation properly.
To install Hugo, NPM, and Go on Windows and macOS:
@ -92,17 +66,13 @@ To install Hugo on Linux, run:
- `snap install node --classic --channel=12`
- `snap install hugo --channel=extended`
## Hugo Theme
We use a git submodule to grab the Hugo theme from the `chef/chef-web-docs` repository.
## Preview Workstation Documentation
There are three ways to preview the documentation in `inspec`:
There are two ways to preview the documentation in `inspec`:
- submit a PR
- `make serve`
- preview content from `chef/chef-web-docs`
### Submit a PR
@ -112,78 +82,20 @@ documentation changes as they would appear on docs.chef.io.
### make serve
`make serve` will preview the documentation that only exists in `inspec/inspec/docs-chef-io`.
This also shows a preview page that includes page metadata which can be useful
for changing where a page exists in the left navigation menu.
To build the docs and preview locally:
Running `make serve` will clone a copy of `chef/chef-web-docs` into `docs-chef-io`.
That copy will be configured to build the InSpec documentation from `docs-chef-io`
and live reload if any changes are made while the Hugo server is running.
- Run `make serve`
- go to http://localhost:1313
The landing page shows navigation menu metadata and the left navigation menu
shows the menu weight for each page. You can use this information to add,
remove, or reorganize Workstation documentation in the menu. None of this will
appear on the [Chef Documentation](https://docs.chef.io) site when the workstation
content is updated.
While the Hugo server is running, any changes you make to content
in the `docs/content` directory will be automatically compiled and updated in the
browser.
#### Clean Your Local Environment
To clean your local development environment:
##### `make clean`
Deletes the sass files, javascript, and fonts in `themes/docs-new`. These will be rebuilt the next time you run `make serve`.
##### `make clean_all`
Deletes the node modules used to build this site in addition to `make clean` described above. These will be reinstalled the next time you run `make serve`.
##### `make reset_chef_web_docs`
Deletes all changes to the chef-web-docs submodule. Changes to chef-web-docs must be made in the chef/chef-web-docs repo and cannot be made from any other repository. Use `make reset_chef_web_docs` to restore the submodule to its initial state.
### Preview Content from chef/chef-web-docs
You can run the Hugo server locally from `chef/chef-web-docs` and direct Hugo to
preview content from your local copy of `inspec/inspec` instead of from the
GitHub repo. This allows you to live reload documentation in `inspec/inspec` and
see how it would look in https://docs.chef.io.
See the README in `chef/chef-web-docs` for instructions.
Also, see the [Hugo documentation](https://gohugo.io/hugo-modules/use-modules/#make-and-test-changes-in-a-module)
for previewing local changes to a module.
## Manage the chef-web-docs Git Submodule
We build previews on Netlify by adding `chef/chef-web-docs` as a Git submodule
in `docs/chef-web-docs`.
To get the commit that the chef-web-docs submodule is set to, run:
```bash
git submodule status
```
To update the submodule, run:
```bash
git submodule foreach git pull origin master
```
This will update the submodule to the latest commit in `chef/chef-web-docs`.
If local changes have been made to the chef-web-docs submodule and you want to
delete them, run:
```bash
make reset_chef_web_docs
```
This will reset the content of the chef-web-docs submodule to the commit that it
is set to.
If you have a local copy of chef-web-docs cloned into `docs-chef-io`,
running `make clean_all` will delete the SASS files, node modules, and fonts in
`docs-chef-io/chef-web-docs/themes/docs-new` used to
build the docs site in the cloned copy of chef-web-docs. Hugo will reinstall these
the next time you run `make serve`.
## Creating New Pages
@ -211,160 +123,6 @@ definition lists.
See our [Style Guide](https://docs.chef.io/style_guide/) for more information
about formatting documentation using Markdown.
## Chef InSpec Page Menu
Adding pages to a menu or modifying a menu should be handled by the Docs Team.
If you add content, it will not automatically show up in the left navigation menu.
Build the site locally (`make serve`) and see the landing page (`http://localhost:1313`).
Any page followed by `InSpec Menu: False` has not been added to the left navigation menu.
Each page needs a page title, an identifier, and a parent.
**Title**
The title is the name of the page as it appears in the left navigation menu.
**Parent**
The parent is the path to that page in the left navigation menu. For example, the
`getting started` page is found by clicking on Chef InSpec so it's parent is
`inspec`.
**Identifier**
Each menu identifier must be unique. We use the menu parent value, followed by
the file name, followed by the page title.
**Menu Weight**
The menu weight is optional. If it isn't included, Hugo assigns each page a weight of 0
and pages with the same weight are put in alphabetical order. Pages with a higher weight
are lower in the menu.
Below is an example of a page menu entry:
```
[menu]
[menu.inspec]
title = "Page Menu Title"
identifier = "inspec/<file_name>.md Page Title"
parent = "inspec"
weight = 10
```
## InSpec Menu Config
The framework for the InSpec menu is located in the `config.toml`
file. This defines the parent menu directories that each page can be added to.
In addition, you can add links to the InSpec menu that navigate to other pages on
the [Chef Documentation](https://docs.chef.io) site or to an external site. See
the example below.
```
[[menu.inspec]]
title = "Page Menu Title"
identifier = "inspec/<filename> Page Title"
parent = "inspec"
url = "relative or absolute URL"
weight = 10
```
See the [Hugo menu documentation](https://gohugo.io/content-management/menus/)
for additional information about formatting a menu item.
## Shortcodes
Shortcodes are simple snippets of code that can be used to modify a Markdown
page by adding content or changing the appearance of content in a page. See
Hugo's [shortcode documentation](https://gohugo.io/content-management/shortcodes/)
for general information about shortcodes.
We primarily use shortcodes in two ways:
- adding reusable text
- highlighting blocks of text in notes or warnings to warn users or
provide additional important information
### Adding reusable text
There are often cases where we want to maintain blocks of text that are identical
from one page to the next. In those cases, we add that text, formatted in Markdown,
to a shortcode file located in `inspec/inspec/docs/layouts/shortcodes`.
Each shortcode in the Chef InSpec documentation must be prefixed with `in_`.
For example, `in_shortcode_name.md`.
To add that shortcode to a page in `inspec/inspec/docs/content`, add the file name,
minus the .md suffix, wrapped in double curly braces and percent symbols to
the location in the Markdown page where you want that text included. For example,
if you want to add the text in `dt_shortcode_file_name.md` to a page, add
`{{% in_shortcode_file_name %}}` to the text of that page and it will appear when
Hugo rebuilds the documentation.
**Shortcodes in lists**
Hugo doesn't handle shortcodes that are indented in a list item properly. It interprets
the text of the shortcode as a code block. More complicated shortcodes with
code blocks, notes, additional list items, or other formatting look pretty
bad. We've created a simple shortcode for handling shortcodes in lists or definition
lists called `readFile_shortcode`.
To include a shortcode in a list or definition list, just add its file name
to the `file` parameter of `readFile_shortcode`.
For example, if you wanted to add `shortcode_file_name.md` to a list:
``` md
1. Here is some text in a list item introducing the shortcode.
{{< readFile_shortcode file="shortcode_file_name.md" >}}
```
### Highlighting blocks of text
We also use shortcodes to highlight text in notes, warnings or danger notices.
These should be used sparingly especially danger notices or warnings. Wrap text
that you want in a note using opening and closing shortcode notation. For example,
```
{{< note >}}
Note text that gives the user additional important information.
{{< /note >}}
```
To add a warning or danger, replace the word `note` with `warning` or `danger` in the
example above.
**Notes in lists**
Hugo doesn't handle shortcodes that are indented in lists very well, that includes the Note,
Warning, and Danger shortcodes. It interprets the indented text that's inside
the Note as a code block when it should be interpreted as Markdown.
To resolve this problem, there's a `spaces` parameter that can be added to the Note,
Warning, and Danger shortcodes. The value of spaces should be set to the number
of spaces that the note is indented.
For example:
```
This is a list:
- List item.
{{< note spaces=4 >}}
Text that gives the user additional important information about that list item.
{{< /note >}}
```
This parameter also works on Danger and Warning shortcodes.
## Aliases
Add an alias to the page metadata to redirect users from a page to the page you are
editing. They are only needed if a page has been deleted and you want to redirect
users from the deleted page to a new or existing page.
## Resource Pages
The resource pages are located in `www/content/inspec/resources/`.
@ -381,27 +139,13 @@ the platform parameter set in its frontmatter. Add `platform = <platform>` to
the page frontmatter to add the platform parameter. For example, the
`aide_conf.md` resource frontmatter has `platform = "linux"` in its page
frontmatter.
## Structure
### High Level
### Documentation Content
```
.
├── Makefile # contains helpers to quickly start up the development environment
├── README.md
├── docs # the hugo site directory used for local development
```
### Local Content
```
.
├── site
├── docs-chef-io
│   ├── content
│   │   ├── inspec # where to keep markdown file documentation
│   │ │ ├── resources # where to keep resource page documentation
│   ├── layouts
| │   ├── shortcodes
| │   │   ├── in_<shortcode_name>.md # how to name your desktop-specific shortcodes
| ├── static
| | ├── images
| | | ├── inspec/inspec # where to keep any images you need to reference in your documentation
@ -410,36 +154,28 @@ frontmatter.
### What is happening behind the scenes
The [Chef Documentation](https://docs.chef.io) site uses [Hugo modules](https://gohugo.io/hugo-modules/)
to load content directly from the `www` directory in the `inspec/inspec`
to load content directly from the `docs-chef-io` directory in the `inspec/inspec`
repository. Every time `inspec/inspec` is promoted to stable, Expeditor
instructs Hugo to update the version of the `inspec/inspec` repository
that Hugo uses to build Chef InSpec documentation on the [Chef Documentation](https://docs.chef.io)
site. This is handled by the Expeditor subscriptions in the `chef/chef-web-docs` GitHub repository.
## Sending documentation feedback
## Documentation Feedback
We love getting feedback. You can use:
We love getting feedback, questions, or comments.
- Email --- Send an email to docs@chef.io for documentation bugs,
ideas, thoughts, and suggestions. This email address is not a
support email address, however. If you need support, contact Chef
support.
- Pull request --- Submit a PR to this repo using either of the two
methods described above.
- GitHub issues --- Use the https://github.com/inspec/inspec/issues.
This is a good place for "important" documentation bugs that may need
visibility among a larger group, especially in situations where a doc bug
may also surface a product bug. You can also use [chef-web-docs
issues](https://github.com/chef/chef-web-docs/issues), especially for
docs feature requests and minor docs bugs.
- https://discourse.chef.io/ --- This is a great place to interact with Chef and others.
**Email**
## Questions
Send an email to Chef-Docs@progress.com for documentation bugs,
ideas, thoughts, and suggestions. This email address is not a
support email address. If you need support, contact [Chef Support](https://www.chef.io/support/).
If you need tips for making contributions to our documentation, check out the
[instructions](https://docs.chef.io/style_guide.html).
**GitHub issues**
If you see an error, open an [issue](https://github.com/chef/chef-web-docs/issues)
or submit a pull request.
Submit an issue to the [InSpec repo](https://github.com/inspec/inspec/issues)
for "important" documentation bugs that may need visibility among a larger group,
especially in situations where a doc bug may also surface a product bug.
Submit an issue to [chef-web-docs](https://github.com/chef/chef-web-docs/issues) for
doc feature requests and minor documentation issues.
If you have a question about the documentation, send an email to docs@chef.io.

1
docs-chef-io/chef-web-docs

@ -1 +0,0 @@
Subproject commit 73adc4af8276cff9b662cc6d58a2db36c6b89052

168
docs-chef-io/config.toml
View file

@ -1,168 +0,0 @@
baseURL = "/"
languageCode = "en-us"
title = "Chef InSpec Documentation"
theme = "docs-new"
themesDir = "chef-web-docs/themes"
enableGitInfo = true
pluralizeListTitles = false
disableKinds = ["taxonomy", "taxonomyTerm"]
[markup]
defaultMarkdownHandler = "goldmark"
[markup.blackFriday]
angledQuotes = false
footnoteAnchorPrefix = ""
footnoteReturnLinkContents = ""
fractions = true
hrefTargetBlank = false
latexDashes = true
nofollowLinks = false
noreferrerLinks = false
plainIDAnchors = true
skipHTML = false
smartDashes = true
smartypants = true
smartypantsQuotesNBSP = false
taskLists = true
extensions = ["hardLineBreak"]
[markup.goldmark]
[markup.goldmark.extensions]
definitionList = true
footnote = true
linkify = true
strikethrough = true
table = true
taskList = true
typographer = true
[markup.goldmark.parser]
attribute = true
autoHeadingID = true
autoHeadingIDType = "github"
[markup.goldmark.renderer]
hardWraps = false
unsafe = true
xHTML = false
[markup.highlight]
codeFences = true
guessSyntax = false
hl_Lines = ""
lineNoStart = 1
lineNos = false
lineNumbersInTable = true
noClasses = true
style = "friendly"
tabWidth = 4
[markup.tableOfContents]
endLevel = 4
ordered = false
startLevel = 2
[params]
enable_search = true
robots = ''
menuOrder = ["overview", "compliance", "effortless", "infra", "workstation", "desktop", "habitat", "inspec", "automate", "legacy", "api", "extra"]
product = "inspec"
[taxonomies]
category = "categories"
tag = "tags"
resource = "resources"
## Main Menu ##
[[menu.main]]
title = "Chef.io"
identifier = "chef"
url = "https://www.chef.io/"
weight = 10
[[menu.main]]
title = "Learn Chef"
identifier = "learn chef"
url = "https://learn.chef.io/"
weight = 20
[[menu.main]]
title = "Blog"
identifier = "blog"
url = "https://blog.chef.io/"
weight = 30
[[menu.main]]
title = "Community"
identifier = "community"
url = "https://community.chef.io/"
weight = 40
[[menu.main]]
title = "Training"
identifier = "training"
url = "https://training.chef.io/"
weight = 50
[[menu.main]]
title = "Download"
identifier = "download"
url = "https://downloads.chef.io/"
weight = 60
####
# Chef InSpec Menu
####
[[menu.inspec]]
title = "Chef InSpec"
identifier = "inspec"
weight = 10
[[menu.inspec]]
title = "Chef InSpec Reference"
identifier = "inspec/reference"
parent = "inspec"
weight = 500
[[menu.inspec]]
title = "Chef InSpec Resources"
identifier = "inspec/resources"
parent = "inspec"
weight = 999
[[menu.inspec]]
title = "OS Resources"
identifier = "inspec/resources/os"
parent = "inspec/resources"
weight = 20
[[menu.inspec]]
title = "AWS Resources"
identifier = "inspec/resources/aws"
parent = "inspec/resources"
weight = 30
[[menu.inspec]]
title = "Azure Resources"
identifier = "inspec/resources/azure"
parent = "inspec/resources"
weight = 40
[[menu.inspec]]
title = "GCP Resources"
identifier = "inspec/resources/gcp"
parent = "inspec/resources"
weight = 50
[[menu.inspec]]
title = "Habitat Resources"
identifier = "inspec/resources/habitat"
parent = "inspec/resources"
weight = 60
####
# End Chef InSpec Menu
####

48
docs-chef-io/layouts/index.html
View file

@ -1,48 +0,0 @@
{{ define "main" }}
<main id="main-content-col" tabindex="-1">
<div class="col-content">
<div id="{{ anchorize ( .Title )}}"><h1>{{ .Title }}</h1></div>
<p>
Below is a list of all of the pages in the {{ title (.Site.Params.product) }} documentation. It lists
the page name, the file name, if the page exists in the {{ .Site.Params.product }} menu, and
metadata about the page's menu entry if it is in the menu.
</p>
<p>
Pages that are not in the <strong>content/{{ .Site.Params.product }}</strong> subdirectory
won't be copied to chef-web-docs. Those file names are highlighted in red.
</p>
<p>
To the left, each entry in the menu is listed with its menu weight. Red menu
items are links to pages outside of the {{ .Site.Params.product }} documentation.
</p>
<ul>
{{ range .Site.RegularPages }}
{{ if ne (string .File) "desktop/resources/README.md"}}
<li>
<p><a href="{{ .Permalink }}">{{ .Title }}</a></p>
<p>
<br>
{{ if hasPrefix .File (.Site.Params.product)}}
<strong>File name:</strong> {{ .File }}
{{ else }}
<strong>File not in {{ .Site.Params.product }} subdirectory:</strong> <span class="page_menu_false">{{ .File }}</span>
{{ end }}
<br>
<strong>{{ title (.Site.Params.product) }} Menu:</strong>
{{ if index (.Params.menu) (.Site.Params.product) }}
<span class="page_menu_true">True</span>
<br><strong>Title:</strong> {{ (index (.Params.menu) (.Site.Params.product)).title }}
<br><strong>Identifier:</strong> {{ (index (.Params.menu) (.Site.Params.product)).identifier }}
<br><strong>Parent:</strong> {{ (index (.Params.menu) (.Site.Params.product)).parent }}
<br><strong>Weight:</strong> {{ (index (.Params.menu) (.Site.Params.product)).weight }}
{{ else }}
<span class="page_menu_false">False</span>
{{ end }}
<br>
</p>
</li>
{{ end }}
{{ end }}
</div>
</main>
{{ end }}

5
docs-chef-io/netlify.toml
View file

@ -1,10 +1,9 @@
[build]
ignore = "sh ./netlify_ignore.sh"
[build.environment]
HUGO_VERSION = "0.76.4"
HUGO_VERSION = "0.78.1"
HUGO_ENABLEGITINFO = "true"
GO_VERSION = "1.12"
GO_VERSION = "1.15"
NODE_ENV = "development"
[build.processing]

1
docs-chef-io/netlify_production/index.html
View file

@ -7,6 +7,5 @@
</head>
<body>
<p>See our documentation on the <a href="https://docs.chef.io">Chef Documentation</a> site.</p>
</body>
</html>