You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The docs require jekyll, a ruby gem. Install the `github-pages` gem which includes
6
-
`jekyll` to ensure you are using the exact version of jekyll that github pages
7
-
is using to serve the live site.
5
+
We welcome contributions to the Calico documentation.
6
+
7
+
Instead of filing a GitHub issue, consider making a PR instead. You are likely to see a much more rapid resolution.
8
+
9
+
The doc contribution process works as follows.
10
+
11
+
1. Fork the [Project Calico repo](https://github.com/projectcalico/calico).
12
+
1. Create a branch in your fork off of the master branch.
13
+
1. Give your branch a short but descriptive name.
14
+
1. Make your changes in the `master` folder.
15
+
1.[Build the site locally to make sure it renders as expected](#building-the-doc-site-locally).
16
+
1.[Check for broken links](#checking-for-broken-links).
17
+
1. Submit a pull request (PR) against the master branch of the [Project Calico repo](https://github.com/projectcalico/calico).
18
+
1. If you haven't already signed our contributer agreement, GitHub will prompt you to do so (required).
19
+
1. Request a review from one or more Calico maintainers.
20
+
1. After getting the approval of at least one Calico maintainer, we ask that you [backport the changes in the `master` folder to the folders of the last two releases](#how-to-quickly-apply-changes-in-master-to-a-previous-release), if appropriate.
21
+
1. Squash your commits.
22
+
1. One of the doc repo maintainers will give the PR a final look and then merge it.
23
+
1. The merge into master will kick off a new build of the live site. You should see your changes on the live site shortly after they are merged.
24
+
25
+
> **Note**: For contributions that affect just one page, you can use the **Edit this page** buttons in the doc site. This allows you to skip a few steps in the process outlined above, but is suitable only for small contributions.
26
+
27
+
We also encourage you to review [Doc site organization](#doc-site-organization), [Doc site architecture](#doc-site-architecture), [Linking content](#linking-content), and [RELEASING.md](RELEASING.md) for additional information.
8
28
9
-
```
10
-
gem install github-pages
11
-
jekyll serve -I
12
-
```
13
29
14
-
>Note:As more versioned directories are created, build speeds will increase by a
15
-
factor of 2. The `-I` is an optional flag for development that enables
16
-
incremental builds, allowing jekyll to only rebuild changed files. This should
17
-
keep subsequent builds down to less than one second.
30
+
## Building the doc site locally
18
31
32
+
We use GitHub Pages and Jekyll to serve and build our site. While there are [several ways to build the site locally](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/), we recommend using our Docker image and the Makefile in the root of the repo. These will allow you to build the site with a single command.
19
33
20
-
Alternatively, you can easily volume mount the source files into the official jekyll docker image via using a simple makefile step:
Navigate into the root of the repo and issue the following command from a terminal prompt.
21
37
22
38
```
23
39
make serve
24
40
```
25
41
26
-
As the output states, docs should then be viewable at http://localhost:4000/.
42
+
Once the build completes, it returns a URL as the value of `Server address:`. Copy and paste this URL into your browser to view the site.
27
43
28
-
### Faster builds
44
+
> **Note**: To view the changes that you've made in the master branch, select **nightly** from the **Version** list box.
45
+
46
+
> **Pro tip**: Jekyll can take a while to render every page. To speed up builds, a supplemental `_config_dev.yml` exists which excludes all directories except `master`. You can include it in your builds as follows `jekyll serve --config _config.yml,_config_dev.yml`. Alternatively, you can pass enable it in `make` using the following environment variable `DEV=true make serve`.
29
47
30
-
Jekyll can take a while to render every page. To speed up builds, a supplemental `_config_dev.yml` exists which excludes all
31
-
directories except `master`. Include it in your builds:
32
48
33
-
```
34
-
jekyll serve --config _config.yml,_config_dev.yml
35
-
```
36
49
37
-
Or pass enable it in make using the environment variable:
To check for broken links, navigate into the root of the repo and issue the following command from a terminal prompt.
38
55
39
56
```
40
-
DEV=true make serve
57
+
make htmlproofer
41
58
```
42
59
43
-
### Versioning & Branches
60
+
The submission of a PR kicks off a continuous integration process which includes a `make htmlproofer` command. Any errors from `htmlproofer` will cause your PR to fail the continuous integration test, so it's best to run this locally before submitting your PR.
44
61
45
-
The live site is generated from the master branch of this repository.
62
+
However, you can also run this after submitting your PR and experiencing an `htmlproofer` failure from the Semaphore job.
46
63
47
-
Documentation for past releases is maintained as a folder in the root of this repository.
48
64
49
-
Most pull requests which modify information in the docs should primarily target
50
-
the `/master/` folder, especially if they are describing newly added features.
51
-
However, changes should also be applied to past-release directories if they fix
52
-
general typos or incorrect information.
65
+
## How to quickly apply changes in master to a previous release
53
66
54
-
##### How to Quickly Back-Apply Master Changes to a Previous Release
55
-
Let's say there's a single commit that makes changes to Master which I want
56
-
to apply to the v1.5 directory. First, generate a diff:
1. Apply the diff to the target version directory.
76
+
77
+
```
78
+
git apply -p2 --directory=v1.5 my-patch.diff
79
+
```
80
+
81
+
- `-p2` strips off /master on the front of the paths.
82
+
- `--directory=v1.5` adds "v1.5" to the start of the paths.
83
+
84
+
1. Inspect the results (`git status`, `git diff`, etc.) and commit.
67
85
68
-
Then simply inspect the results (`git status`, `git diff`, etc.) and commit.
86
+
## Doc site organization
69
87
70
-
##Navigation & Sidebar
88
+
### Overview
71
89
72
-
The docs (currently) are split into 4 main sections:
90
+
The docs (currently) are split into four main sections.
73
91
74
-
- Introduction
75
-
- Getting Started
76
-
-Using
77
-
- Reference
92
+
- [Introduction](#introduction)
93
+
- [Getting started](#getting-started)
94
+
- [Usage](#usage)
95
+
- [Reference](#reference)
78
96
79
97
### Introduction
80
98
81
99
Landing page for new users covering Calico's purpose and high-level topics.
82
100
83
-
### Getting Started
101
+
### Getting started
84
102
85
-
This should be where new users go. It includes quick-start guides, some basic
86
-
tutorials to show off Calico's capabilities, and links to more advanced topics
87
-
once users are comfortable with the basics.
103
+
This should be where new users go. It includes quick-start guides, some basic tutorials to show off Calico's capabilities, and links to more advanced topics once users are comfortable with the basics.
88
104
89
-
Each orchestrator has a landing page that is targeted at people who are coming
90
-
to see Calico for the first time. It's a transition from the "marketing" type
91
-
material (why is Calico great) to some quick commands people can run to see it
92
-
firsthand, and then funnels people off to the usage section for more details.
105
+
Each orchestrator has a landing page that is targeted at people who are coming to see Calico for the first time. It's a transition from the "marketing" type material (why is Calico great) to some quick commands people can run to see it firsthand, and then funnels people off to the Usage section for more details.
93
106
94
107
### Usage
95
108
96
-
These should all be docs that are a "verb" and task focused. Each doc should
97
-
contain why you want to do this, a goal, and a set of steps you can follow to
98
-
achieve it. They should not be detailed description of components or tabulated
99
-
configuration information.
109
+
This section contains task-based information. All top-level titles in this section should start with a gerund. Each topic should include why you want to perform the task, a goal, and a set of steps you can follow to achieve it.
100
110
101
111
Examples:
102
112
103
-
- Configuring BGP Peers
113
+
- Configuring BGP peers
104
114
- Enabling IP-in-IP in AWS
105
115
- Troubleshooting Calico
106
116
- Using calicoctl in a Kubernetes deployment
107
-
- Configuring Egress Policy in Kubernetes
117
+
- Configuring egress policy in Kubernetes
118
+
119
+
Do not include detailed description of components or tabulated
120
+
configuration information in this section. This type of content should be located in the [Reference](#reference) section.
108
121
109
122
### Reference
110
123
111
-
These docs are complete reference for Calico. If there's a configuration
112
-
option you're looking for, it goes here in one of the per-component
113
-
references. Not every option has a "how to" guide, but has enough description.
114
-
The caveats and considerations when enabling options should be listed here.
124
+
These docs contain complete reference information for Calico. If there's a configuration option you're looking for, it goes here in one of the per-component references. Not every option has a "how to" guide, but has enough description. The caveats and considerations when enabling options should be listed here.
The naming and layout of these navbars are stored in `_data/$VERSION/navbars/*`. Jekyll automatically stores information from the `_data` dir in an accessible variable called `site.data`. The toplevel layout (`_layout/docwithnav.html`) will iterate through all the files in `site.data[version].navbars` to construct the sidebar based on which version is being viewed.
133
+
## Doc site architecture
126
134
127
-
> Note: Sidebar paths to index files (see next section) should end in a `/`in the yaml file. Sidebar paths to actual files should not end in a `/` in the yaml file.
135
+
The naming and layout of these navbars are stored in `_data/$VERSION/navbars/*`. Jekyll automatically stores information from the `_data` directory in an accessible variable called `site.data`. The top-level layout (`_layout/docwithnav.html`) will iterate through all the files in `site.data[version].navbars` to construct the sidebar based on which version is being viewed.
128
136
129
-
## Pathing
137
+
> **Note**: Sidebar paths to index files (see [next section](#linking-content)) should end in a `/` in the yaml file. Sidebar paths to actual files should not end in a `/` in the yaml file.
130
138
131
-
URL structure is important. In order to create a toplevel splash page for a URL path, simply name the file `index.md`. See the following example:
139
+
URL structure is important. In order to create a top level splash page for a URL path, simply name the file `index.md`. See the following example:
132
140
133
141
134
142
| URL | Filepath |
@@ -137,22 +145,13 @@ URL structure is important. In order to create a toplevel splash page for a URL
0 commit comments