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
# About this repository[](https://travis-ci.com/travis-ci/docs-travis-ci-com)
1
+
# About Travis CI Repository[](https://travis-ci.com/travis-ci/docs-travis-ci-com)
2
2
3
-
This is the documentation site for Travis CI! (<https://docs.travis-ci.com/>)
3
+
This is the documentation site for [Travis CI!](https://docs.travis-ci.com/).
4
+
Follow this guide to learn how to add new documentation and how to update existing documentation.
4
5
5
-
## How to contribute
6
+
## Add Documentation
6
7
7
-
Fork the repository, read the rest of this README file and make some changes.
8
-
Once you're done with your changes send a pull request. Thanks!
8
+
The following are the steps to add documentation.
9
9
10
-
## How to check your edit before sending PR
10
+
1. Review the [Travis CI documentation guidelines](/STYLE.md).
11
+
1. Check existing documentation. Verify that the documentation does not already exist or look for related documentation that can be enhanced.
12
+
1. Determine proper placement. In the [Travis CI repository](https://github.com/travis-ci/docs-travis-ci-com/tree/master), browse to the *user* folder (or any other specific folder) and create a new branch.
13
+
1. Create a new file and add the new documentation files.
14
+
1. Ensure to insert the name and extension for the file.
15
+
1. Commit your changes and add a short message to describe your changes.
16
+
1. Test the changes locally to verify your edits.
17
+
1. Submit a pull request. Include a clear title and description of the proposed changes, and click “**Create pull request**.”
11
18
12
-
You can inspect how your edits will be reflected by the documentation site. Either by clicking on the Netlify preview link in your Pull Request or building the docs locally.
19
+
Thank you for your contribution! The Travis CI team will review the pull request and approve any necessary changes.
13
20
14
-
### Install dependencies
21
+
##Update Existing Documentation
15
22
16
-
1. Make sure you have Ruby and RubyGems installed.
23
+
If you see a page that needs to be updated or that can be improved, follow these steps to update Travis CI's existing documentation.
17
24
18
-
1. Install [bundler](http://bundler.io/):
25
+
1. Review the [Travis CI documentation guidelines](/STYLE.md).
26
+
1. Identify the Travis CI docs page that needs to be updated.
27
+
1. Click the “**Improve this page on GitHub**” button in the top right corner.
28
+
1. Once on GitHub, edit the relevant file.
29
+
1. Commit your changes. Name your branch, and click the “**Propose changes**” button.
30
+
1. Build the docs in a local environment to verify your edits.
31
+
1. Submit a pull request. Ensure a clear title and description of the proposed changes are added, and click “**Create pull request**.”
32
+
33
+
Thank you for your contribution. The Travis CI team will review the pull request and approve any necessary changes.
34
+
35
+
36
+
## Build Local Environment
37
+
38
+
You can inspect how the documentation site will reflect your edits. Follow the steps below to learn how to build your local environment and check all your edits before sending the pull request for approval.
39
+
40
+
### Install Dependencies
41
+
42
+
Follow the steps below to install dependencies.
43
+
44
+
1. Ensure you have *Ruby* and *RubyGems* installed.
45
+
46
+
1. Clone the [Travis CI docs](https://github.com/travis-ci/docs-travis-ci-com/tree/master) repository.
47
+
48
+
1. Install [bundler](http://bundler.io/) as follows:
19
49
20
50
```sh-session
21
51
$ gem install bundler
22
52
```
23
53
24
-
1. Install application dependencies:
54
+
1. Next, install application dependencies:
25
55
26
56
```sh-session
27
57
$ bundle install --binstubs
28
58
```
29
59
30
-
### Generate documentation
60
+
### Generate Documentation
31
61
32
-
Run
62
+
To generate the documentation, run the following command:
33
63
34
64
```sh-session
35
65
$ ./bin/jekyll build
36
66
```
37
67
68
+
### Run the Application Server
38
69
39
-
### Run application server
40
-
41
-
You are now ready to start your documentation site, using Jekyll or Puma.
70
+
You are ready to start your local documentation site using Jekyll or Puma.
42
71
For documentation edits, Jekyll is sufficient.
43
72
44
-
#### Starting and inspecting edits with Jekyll
73
+
#### Edit with Jekyll
74
+
75
+
To start and inspect your edits using Jekyll, follow the steps below:
45
76
46
-
1. Run Jekyll server:
77
+
1. Run the *Jekyll* server:
47
78
48
79
```sh-session
49
80
$ ./bin/jekyll serve
50
81
```
51
82
52
83
1. Open [localhost:4000](http://localhost:4000/) in your browser.
53
84
54
-
#### Starting and inspecting edits with Puma
85
+
#### Edit with Puma
55
86
56
-
For more programmatical PRs (such as handling webhooks notification
57
-
via POST), Puma is necessary.
87
+
For more programmatical pull requests (such as handling webhooks notifications
88
+
via POST), Puma is necessary. To start and inspect your edits using Puma, follow the steps below:
58
89
59
-
1. Run Puma server:
90
+
1. Run the *Puma* server:
60
91
61
92
```sh-session
62
93
$ ./bin/puma
63
94
```
64
95
65
96
1. Open [localhost:9292](http://localhost:9292/) in your browser.
66
97
67
-
### API V2 documentation
98
+
### API Documentation
68
99
69
-
API V2 (and 2.1) documentation is maintained in `slate/source` and is generated at build time from source.
100
+
All Travis CI API V2 (and 2.1) documentation is maintained in `slate/source` and generated from the source at build time.
70
101
71
102
## License
72
103
73
-
Distributed under the [MIT license](https://opensource.org/licenses/MIT); the same as other Travis CI projects.
104
+
Distributed under the [MIT license](https://opensource.org/licenses/MIT), like other Travis CI projects.
We use Kramdown, with [GFM](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown)codeblocks, and a few Kramdownrelated exceptions introduced with `{: }` such as class names for specific formatting of columns and notes.
15
+
We use Kramdown, with [GFM](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown)code blocks, and a few Kramdown-related exceptions introduced with `{: }` such as class names for specific formatting of columns and notes.
16
16
17
-
###Headings
17
+
## Headings
18
18
19
-
For historical reasons, the toplevel heading in Jekyll markdown files is level 2 (##) not level 1 (#).
19
+
For historical reasons, the top-level heading in Jekyll's markdown files is level 2 (##), not level 1 (#). Only the page’s title is a level 1 heading.
20
20
21
-
We use ATXstyle headings, and do not use the optional closing hashes:
21
+
We use ATX-style headings and do not use the optional closing hashes:
22
22
23
23
```markdown
24
24
## This is an H2
@@ -28,38 +28,62 @@ We use ATX style headings, and do not use the optional closing hashes:
28
28
#### This is an H4
29
29
```
30
30
31
-
We do not use underline style headings:
31
+
We do not use underlined style headings:
32
32
33
33
```markdown
34
34
Do not use this style heading
35
35
=============================
36
36
```
37
37
38
-
###Lists
38
+
## Lists
39
39
40
-
If you have long lists you can wrap them into 2 (`.column-2`) or 3 (`.column-3`) columns using one of the follow CSS classes after your list item:
40
+
If you have long lists, you can wrap them into 2 (`.column-2`) or 3 (`.column-3`) columns using one of the following CSS classes after your list item:
41
41
42
42
```css
43
43
* long list item 1
44
44
* long list item 2
45
45
{: .column-2 }
46
46
```
47
47
48
-
#### In-page table of contents
48
+
##Links
49
49
50
-
All pages have tables of contents generated automatically from H2 and H3
50
+
Make sure all links have titles:
51
+
52
+
```markdown
53
+
The [link][example1] in the text
54
+
55
+
[example1]: http://www.example.com "Example URL"
56
+
```
57
+
58
+
or
59
+
60
+
```markdown
61
+
The [link](http://www.example.com "Example URL") in the text
62
+
```
63
+
64
+
When linking internal pages, use absolute paths and trailing slashes: `/user/languages/c/`.
65
+
You can link to headings and remember to remove special characters, for example:
66
+
67
+
To link to "##Node.js Page," use `#nodejs-page`.
68
+
69
+
70
+
## In-page Options
51
71
52
-
To remove the TOC from a page add `no_toc: true` to the frontmatter.
72
+
### Notes, warnings, and blocks
53
73
54
-
### Note, warnings and blocks
74
+
Travis CI uses the blockquote symbol `>` for general-purpose notes and warnings.
55
75
56
-
We use the blockquote symbol `>` for general purpose notes and warnings.
76
+
See an example below:
57
77
58
-
#### Beta features
78
+
> Note: This feature is only available in Version 2.0.
79
+
80
+
### Beta features
59
81
60
82
Mark all beta features with a specially formatted note. Both the `> BETA` and
61
83
the `{: .beta}` are required.
62
84
85
+
See an example below:
86
+
63
87
> BETA Awesome new feature that might not be enabled and is subject to change.
64
88
{: .beta}
65
89
@@ -68,46 +92,25 @@ the `{: .beta}` are required.
68
92
Mark all alpha features with a specially formatted note. Both the `> ALPHA` and
69
93
the `{: alpha}` are required.
70
94
71
-
> ALPHA Awesome new feature that might explode for extra fun.
95
+
> ALPHA: Awesome new feature that might explode for extra fun.
72
96
{: .alpha}
73
97
74
98
### GUI
75
99
76
-
Make sure all references to items in a GUI match the case of the UI, and are marked with *asterisks*.
77
-
78
-
### Links
79
-
80
-
Make sure all links have titles:
81
-
82
-
```markdown
83
-
The [link][example1] in the text
84
-
85
-
[example1]: http://www.example.com "Example URL"
86
-
```
87
-
88
-
or
89
-
90
-
```markdown
91
-
The [link](http://www.example.com "Example URL") in the text
92
-
```
93
-
94
-
When linking internal pages, use absolute paths and trailing slashes: `/user/languages/c/`.
95
-
You can link to headings, remember to remove special characters, for example:
96
-
97
-
To link to "##Node.js Page" use `#nodejs-page`.
100
+
Ensure all references to items in a GUI match the case of the UI and are marked with *asterisks*.
98
101
99
102
100
103
### Code Inline
101
104
102
-
All function names, filenames, etc should be marked with `back-ticks`.
105
+
All function names, filenames, etc., should be marked with `back-ticks`.
103
106
104
107
If you're talking about applications or services, only the actual command should be marked as code, not the name of the service:
105
108
106
109
- Start the PostgreSQL database by running `psql`.
107
110
108
111
### Blockquotes / Notes / Warnings
109
112
110
-
As we have no use for blockquotes we use `>` to indicate notes and warnings:
113
+
As we have no use for blockquotes, we use `>` to indicate notes and warnings:
111
114
112
115
```markdown
113
116
> Note this important info!
@@ -131,16 +134,62 @@ This code is in .travis.yml
131
134
```
132
135
{: data-file=".travis.yml"}
133
136
137
+
### In-page table of contents
138
+
139
+
All Travis CI pages have tables of contents generated automatically from H2 and H3
134
140
141
+
Add `no_toc: true` to the frontmatter to remove the TOC from a page.
135
142
136
-
### Common misspellings and words to avoid
143
+
### Terminology
144
+
The following are some common misspellings and words to avoid
137
145
138
146
- Always refer to *Travis CI* and never to Travis.
139
147
140
148
## Images
141
149
150
+
Add images inline-style with a brief description.
151
+
152
+
To add an image, follow these steps:
153
+
1 Capture the image.
154
+
2 Save the image in the `images/` path.
155
+
3 Add the image to the documentation as follows:
156
+
157
+
142
158
### Screencapture gifs
143
159
144
160
1. Run a build (or whatever you are trying to capture),
145
161
2. Capture it with [licecap](https://www.cockos.com/licecap/).
146
-
3. Save the gif in `images/`
162
+
3. Save the gif in the following path: `images/`
163
+
164
+
165
+
## Documentation Template
166
+
167
+
A basic template for contributing to new documentation pages or sections is as follows:
168
+
169
+
```markdown
170
+
---
171
+
title: “Insert Page Title”
172
+
layout: en
173
+
174
+
---
175
+
176
+
Start your introduction here. Usually, an introduction is between one and three sentences.
177
+
178
+
## Section Heading
179
+
180
+
Section introduction sentence.
181
+
182
+
* **Item1** - a group of *jobs* that run in sequence.
183
+
* **Item2** - a group of *jobs* that run in parallel as part of a sequential *build* process composed of multiple [stages](/user/build-stages/).
184
+
* **Item3** - an automated process that clones your repository into a virtual
185
+
environment and then carries out a series of *phases* such as compiling your
186
+
code, running tests, etc.
187
+
* **Item4** - the [sequential steps](/user/job-lifecycle/)
188
+
of a *job*.
189
+
190
+
```
191
+
{: data-file=".travis.yml"}
192
+
193
+
The example above shows a paragraph with different formatting options.
194
+
195
+
Check out the [Travis CI documentation](https://docs.travis-ci.com/) for more examples.
0 commit comments