Skip to content

Commit 98ec51d

Browse files
author
IanMadd
committed
Add Hugo config and content for server docs
Signed-off-by: IanMadd <[email protected]>
1 parent 0973395 commit 98ec51d

File tree

96 files changed

+27212
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

96 files changed

+27212
-3
lines changed

‎.github/CODEOWNERS

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Order is important. The last matching pattern has the most precedence.
22

3-
* @chef/chef-infra-server-reviewers @chef/chef-infra-server-approvers @chef/chef-infra-server-owners
4-
.expeditor/ @chef/releng-ops
5-
*.md @chef/docs-team
3+
* @chef/chef-infra-server-reviewers @chef/chef-infra-server-approvers @chef/chef-infra-server-owners
4+
.expeditor/ @chef/releng-ops
5+
*.md @chef/docs-team
6+
docs-chef-io/ @chef/docs-team

‎docs-chef-io/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
chef-web-docs/
2+
3+
resources/

‎docs-chef-io/Makefile

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# we use pushd/popd here, and /bin/sh of our chefes/buildkite image is not bash
2+
# so we have to override the default shell here
3+
SHELL=bash
4+
5+
preview_netlify: chef_web_docs
6+
cp -R content/* chef-web-docs/_vendor/github.com/chef/chef-server/docs-chef-io/content
7+
cp -R static/* chef-web-docs/_vendor/github.com/chef/chef-server/docs-chef-io/static
8+
pushd chef-web-docs && make assets; hugo --buildFuture --gc --minify && popd
9+
10+
# serve: chef_web_docs
11+
# echo "replace github.com/chef/chef-server/docs-chef-io => ../" >> chef-web-docs/go.mod
12+
# pushd chef-web-docs && make assets; hugo server --buildDrafts --buildFuture --noHTTPCache --ignoreVendorPaths "github.com/chef/automate/**" && popd
13+
14+
serve: chef_web_docs
15+
cp -R content/* chef-web-docs/content
16+
cp -R static/* chef-web-docs/static
17+
cp config.toml chef-web-docs/config.toml
18+
pushd chef-web-docs && make assets; hugo server --buildDrafts --noHTTPCache --buildFuture && popd
19+
20+
chef_web_docs:
21+
if [ -d "chef-web-docs/" ]; then \
22+
pushd chef-web-docs && git reset HEAD --hard; git pull origin master && popd; \
23+
else \
24+
git clone https://github.com/chef/chef-web-docs.git; \
25+
fi
26+
27+
clean_all:
28+
rm -rf chef-web-docs
29+

‎docs-chef-io/README.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Chef Infra Server Documentation
2+
3+
The Chef Infra Server Documentation is deployed on https://docs.chef.io/server/ using Hugo and Netlify.
4+
5+
## The Fastest Way to Contribute
6+
7+
There are two steps to updating the Chef Infra Server documentation:
8+
9+
1. Update the documentation in the `chef/chef-server` repository.
10+
1. Update the Chef Infra Server repository module in `chef/chef-web-docs`.
11+
12+
### Update Content in `chef/chef-server`
13+
14+
The fastest way to change the documentation is to edit a page on the
15+
GitHub website using the GitHub UI.
16+
17+
To perform edits using the GitHub UI, click on the `[edit on GitHub]` link at
18+
the top of the page that you want to edit. The link takes you to that topic's GitHub
19+
page. In GitHub, click on the pencil icon and make your changes. You can preview
20+
how they'll look right on the page ("Preview Changes" tab).
21+
22+
We also require contributors to include their [DCO signoff](https://github.com/chef/chef/blob/master/CONTRIBUTING.md#developer-certification-of-origin-dco)
23+
in the comment section of every pull request, except for obvious fixes. You can
24+
add your DCO signoff to the comments by including `Signed-off-by:`, followed by
25+
your name and email address, like this:
26+
27+
`Signed-off-by: Julia Child <[email protected]>`
28+
29+
See our [blog post](https://blog.chef.io/introducing-developer-certificate-of-origin/)
30+
for more information about the DCO and why we require it.
31+
32+
After you've added your DCO signoff, add a comment about your proposed change,
33+
then click on the "Propose file change" button at the bottom of the page and
34+
confirm your pull request. The CI system will do some checks and add a comment
35+
to your PR with the results.
36+
37+
The Chef documentation team can normally merge pull requests within seven days.
38+
We'll fix build errors before we merge, so you don't have to
39+
worry about passing all the CI checks, but it might add an extra
40+
few days. The important part is submitting your change.
41+
42+
### Update the Chef Infra Server Repository Module In `chef/chef-web-docs`
43+
44+
We use [Hugo modules](https://gohugo.io/hugo-modules/) to build Chef's documentation from multiple repositories. The documentation from those repositories are [vendored](https://gohugo.io/hugo-modules/use-modules/#vendor-your-modules) in chef-web-docs.
45+
46+
When Chef Infra Server is promoted to stable, Expeditor will submit a pull request to `chef/chef-web-docs` to update the Infra Server documentation on docs.chef.io.
47+
48+
To update the Hugo module for documentation in `chef/chef-server`:
49+
50+
1. Make sure your documentation changes are merged into master in `chef/chef-server`.
51+
1. Wait for Expeditor to submit a PR to `chef/chef-web-docs` after Chef Infra Server is promoted to stable.
52+
53+
If you need to manually update the Chef Infra Server documentation, contact your
54+
friendly local Docs Team who will update the Infra Server Hugo module for you.
55+
56+
## Local Development Environment
57+
58+
We use [Hugo](https://gohugo.io/), [Go](https://golang.org/), [NPM](https://www.npmjs.com/),
59+
[go-swagger](https://goswagger.io/install.html), and [jq](https://stedolan.github.io/jq/).
60+
You will need Hugo 0.61 or higher installed and running to build and view our documentation properly.
61+
62+
To install Hugo, NPM, and Go on Windows and macOS:
63+
64+
- On macOS run: `brew tap go-swagger/go-swagger && brew install go-swagger hugo node go jq`
65+
- On Windows run: `choco install hugo nodejs golang jq`
66+
- See the Go-Swagger [docs to install go-swagger](https://goswagger.io/install.html)
67+
68+
To install Hugo on Linux, run:
69+
70+
- `apt install -y build-essential`
71+
- `sudo apt-get install jq`
72+
- `snap install node --classic --channel=12`
73+
- `snap install hugo --channel=extended`
74+
- See the Go-Swagger [docs](https://goswagger.io/install.html) to install go-swagger
75+
76+
1. (Optional) [Install cspell](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
77+
78+
To be able to run the optional `make spellcheck` task you'll need to install `cspell`:
79+
80+
```shell
81+
npm install -g cspell
82+
```
83+
84+
## Preview Chef Infra Server Documentation
85+
86+
There are two ways to preview the documentation in `chef/chef-server`:
87+
88+
- Submit a PR
89+
- `make serve`
90+
91+
### Submit a PR
92+
93+
When you submit a PR to `chef/chef-server`, Netlify will build the documentation
94+
and add a notification to the GitHub pull request page. You can review your
95+
documentation changes as they would appear on docs.chef.io.
96+
97+
### make serve
98+
99+
Running `make serve` will clone a copy of `chef/chef-web-docs` into `docs-chef-io`.
100+
That copy will be configured to build the Infra Server documentation from `docs-chef-io`
101+
and live reload if any changes are made while the Hugo server is running.
102+
103+
- Run `make serve`
104+
- go to http://localhost:1313
105+
106+
## Clean Your Local Environment
107+
108+
If you have a local copy of `chef-web-docs` cloned into `docs-chef-io`,
109+
running `make clean_all` will delete `chef-web-docs`. Hugo will reinstall these
110+
the next time you run `make serve`.
111+
112+
## Creating New Pages
113+
114+
Please keep all of the Chef Infra Server documentation in the `content/server` directory.
115+
To add a new Markdown file, run the following command from the `docs-chef-io` directory:
116+
117+
```
118+
hugo new content/server/<filename>.md
119+
```
120+
121+
This will create a draft page with enough front matter to get you going.
122+
123+
Hugo uses [Goldmark](https://github.com/yuin/goldmark) which is a
124+
superset of Markdown that includes GitHub styled tables, task lists, and
125+
definition lists.
126+
127+
See our [Style Guide](https://docs.chef.io/style_guide/) for more information
128+
about formatting documentation using Markdown.
129+
130+
## What Is Happening Behind the Scenes
131+
132+
The [Chef Documentation](https://docs.chef.io) site uses [Hugo modules](https://gohugo.io/hugo-modules/)
133+
to load content directly from `chef/chef-server/docs-chef-io`. Every time
134+
`chef/chef-server` is promoted to stable, Expeditor submits a PR to chef-web-docs to
135+
update the version of the `chef/chef-server` repository that Hugo uses to build Chef
136+
Infra Server documentation on the [Chef Documentation](https://docs.chef.io) site.
137+
This is handled by the Expeditor subscriptions in the `chef/chef-web-docs` GitHub repository.
138+
139+
## Documentation Feedback
140+
141+
We love getting feedback, questions, or comments.
142+
143+
**Email**
144+
145+
Send an email to [email protected] for documentation bugs,
146+
ideas, thoughts, and suggestions. This email address is not a
147+
support email address. If you need support, contact [Chef Support](https://www.chef.io/support/).
148+
149+
**GitHub issues**
150+
151+
Submit an issue to the [Infra Server repo](https://github.com/chef/chef-server/issues)
152+
for "important" documentation bugs that may need visibility among a larger group,
153+
especially in situations where a doc bug may also surface a product bug.
154+
155+
Submit an issue to [chef-web-docs](https://github.com/chef/chef-web-docs/issues) for
156+
doc feature requests and minor documentation issues.

‎docs-chef-io/archetypes/default.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
+++
2+
title = "{{ .Name | humanize | title }}"
3+
4+
date = {{ .Date }}
5+
draft = false
6+
7+
[menu]
8+
[menu.server]
9+
title = "{{ .Name | humanize | title }}"
10+
identifier = "server/{{ .Name | humanize | title }}"
11+
parent = "server"
12+
weight = 10
13+
+++
14+

0 commit comments

Comments
 (0)