Skip to content

Commit 7c4e742

Browse files
tclemtclem
committed
Clean up lots of little things in the docs
- Fix spelling errors - Make individual sections more consistent with eachother - Show real json for input and response instead of ruby hashes (required adding yajl-ruby gem) - Clarified a few parts of the gist api docs - and more!
1 parent 8edba30 commit 7c4e742

9 files changed

Lines changed: 68 additions & 71 deletions

File tree

‎Gemfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ source "http://rubygems.org"
33
gem 'nanoc', '~> 3.1.6'
44
gem 'kramdown', '~> 0.13.2'
55
gem 'nokogiri', '~> 1.4.4'
6+
gem 'yajl-ruby', '~> 0.8.2'
67

78
group :development do
89
gem 'adsf'

‎Gemfile.lock‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ GEM
1111
cri (>= 1.0.0)
1212
nokogiri (1.4.4)
1313
rack (1.2.2)
14+
yajl-ruby (0.8.2)
1415

1516
PLATFORMS
1617
ruby
@@ -20,3 +21,4 @@ DEPENDENCIES
2021
kramdown (~> 0.13.2)
2122
nanoc (~> 3.1.6)
2223
nokogiri (~> 1.4.4)
24+
yajl-ruby (~> 0.8.2)

‎content/v3/gists.md‎

Lines changed: 26 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -4,56 +4,40 @@ title: Gists API v3 | developer.github.com
44

55
# Gists API
66

7-
The Gist API v3 has been unified into the core GitHub API and can be
8-
accessed via the domain api.github.com. SSL is required so the base url
9-
for all API calls should be: `https://api.github.com`.
10-
Please see the [summary](/v3/) for a complete description of the API
11-
including information about data format and authentication.
7+
## List gists
128

13-
## List a user's gists
9+
List a user's gists:
1410

1511
GET /users/:user/gists
1612

17-
### Response
18-
19-
<%= headers 200, :pagination => true %>
20-
<%= json(:gist) { |h| [h] } %>
21-
22-
## List your gists
23-
This will return a list of your gists, or if called anonymously it will
24-
return a list of all public gists.
13+
List the authenticated user's gists or if called anonymously, this will
14+
returns all public gists:
2515

2616
GET /gists
2717

28-
### Response
29-
The response is identical to [listing a user's gists](#list-a-users-gists).
30-
31-
## List public gists
32-
This will return a list of all public gists.
18+
List all public gists:
3319

3420
GET /gists/public
3521

36-
### Response
37-
The response is identical to [listing a user's gists](#list-a-users-gists).
38-
39-
## List your starred gists
40-
This will return a list of your starred gists.
22+
List the authenticated user's starred gists:
4123

4224
GET /gists/starred
4325

4426
### Response
45-
The response is identical to [listing a user's gists](#list-a-users-gists).
27+
28+
<%= headers 200, :pagination => true %>
29+
<%= json(:gist) { |h| [h] } %>
4630

4731
## Get a single gist
4832

49-
GET /gists/:id
33+
GET /gists/:id
5034

5135
### Response
5236

5337
<%= headers 200 %>
5438
<%= json :full_gist %>
5539

56-
## Create a new gist
40+
## Create a gist
5741

5842
POST /gists
5943

@@ -62,14 +46,13 @@ The response is identical to [listing a user's gists](#list-a-users-gists).
6246
<%= json \
6347
:description => "the description for this gist",
6448
:public => true,
65-
:files => {
49+
:files => {
6650
"file1.txt" => {"content" => "String file contents"}
6751
} %>
6852

6953
### Response
7054

71-
<%= headers 201,
72-
:Location => "https://api.github.com/users/:user/gists/1" %>
55+
<%= headers 201, :Location => "https://api.github.com/gists/1" %>
7356
<%= json :full_gist %>
7457

7558
## Edit a gist
@@ -78,10 +61,16 @@ The response is identical to [listing a user's gists](#list-a-users-gists).
7861

7962
### Input
8063

64+
All files from the previous version of the gist are carried over by
65+
default.
66+
8167
<%= json \
8268
:description => "the description for this gist",
8369
:files => {
84-
"file1.txt" => {"content" => "String file contents"}
70+
"file1.txt" => {"content" => "updated file contents"},
71+
"old_name.txt" => {"filename" => "new_name.txt", "content" => "modified contents"},
72+
"new_file.txt" => {"content" => "a new file"},
73+
"delete_this_file.txt" => nil,
8574
} %>
8675

8776
### Response
@@ -95,38 +84,35 @@ The response is identical to [listing a user's gists](#list-a-users-gists).
9584

9685
### Response
9786

98-
<%= headers 201,
99-
:Location => "https://api.github.com/users/user/gists/1" %>
100-
<%= json({}) %>
87+
<%= headers 204 %>
10188

10289
## Unstar a gist
10390

10491
DELETE /gists/:id/star
10592

10693
### Response
10794

108-
<%= headers 204, :no_response => true %>
95+
<%= headers 204 %>
10996

11097
## Check if a gist is starred
11198

11299
GET /gists/:id/star
113100

114101
### Response if gist is starred
115102

116-
<%= headers 204, :no_response => true %>
103+
<%= headers 204 %>
117104

118105
### Response if gist is not starred
119106

120-
<%= headers 404, :no_response => true %>
107+
<%= headers 404 %>
121108

122109
## Fork a gist
123110

124111
POST /gists/:id/fork
125112

126113
### Response
127114

128-
<%= headers 201,
129-
:Location => "https://api.github.com/users/user/gists/1" %>
115+
<%= headers 201, :Location => "https://api.github.com/gists/2" %>
130116
<%= json(:gist) %>
131117

132118
## Delete a gist
@@ -135,5 +121,5 @@ The response is identical to [listing a user's gists](#list-a-users-gists).
135121

136122
### Response
137123

138-
<%= headers 204, :no_response => true %>
124+
<%= headers 204 %>
139125

‎content/v3/gists/comments.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Gist Comments API v3 | developer.github.com
44

55
# Gist Comments API
66

7-
## List
7+
## List comments on a gist
88

99
GET /gists/:gist_id/comments
1010

@@ -13,7 +13,7 @@ title: Gist Comments API v3 | developer.github.com
1313
<%= headers 200 %>
1414
<%= json(:gist_comment) { |h| [h] } %>
1515

16-
## Get
16+
## Get a single comment
1717

1818
GET /gists/comments/:id
1919

@@ -22,7 +22,7 @@ title: Gist Comments API v3 | developer.github.com
2222
<%= headers 200 %>
2323
<%= json :gist_comment %>
2424

25-
## Create
25+
## Create a comment
2626

2727
POST /gists/:gist_id/comments
2828

@@ -36,7 +36,7 @@ title: Gist Comments API v3 | developer.github.com
3636
:Location => "https://api.github.com/gists/comments/1" %>
3737
<%= json :gist_comment %>
3838

39-
## Edit
39+
## Edit a comment
4040

4141
PATCH /gists/comments/:id
4242

@@ -49,11 +49,11 @@ title: Gist Comments API v3 | developer.github.com
4949
<%= headers 200 %>
5050
<%= json :gist_comment %>
5151

52-
## Delete
52+
## Delete a comment
5353

5454
DELETE /gists/comments/:id
5555

5656
### Response
5757

58-
<%= headers 204, :no_response => true %>
58+
<%= headers 204 %>
5959

‎content/v3/users.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@ title: Users API v3 | developer.github.com
33
---
44

55
# Users API
6+
67
Many of the resources on the users API provide a shortcut for getting
7-
information about the currently authenticated user. If a request URL does not
8-
include a `:user` parameter than the response will be for the logged in
9-
user (and you must pass authentication information with your request).
8+
information about the currently authenticated user. If a request URL
9+
does not include a `:user` parameter than the response will be for the
10+
logged in user (and you must pass [authentication
11+
information](/v3/#authentication) with your request).
1012

11-
## Get a user
13+
## Get a single user
1214

1315
GET /users/:user
1416

@@ -17,7 +19,7 @@ user (and you must pass authentication information with your request).
1719
<%= headers 200 %>
1820
<%= json :full_user %>
1921

20-
## Get the authenicated user
22+
## Get the authenticated user
2123

2224
GET /user
2325

‎content/v3/users/emails.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ title: User Emails API v3 | developer.github.com
77
Mangement of email addresses via the API requires that you are
88
authenticated.
99

10-
## Get email addresses
10+
## Get email addresses for a user
1111

1212
GET /user/emails
1313

@@ -43,5 +43,5 @@ You can include a single email address or an array of addresses:
4343

4444
### Response
4545

46-
<%= headers 204, :no_response => true %>
46+
<%= headers 204 %>
4747

‎content/v3/users/followers.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,29 @@ title: User Followers API v3 | developer.github.com
44

55
# User Followers API
66

7-
## List a user's followers
7+
## List followers of a user
8+
9+
List a user's followers:
810

911
GET /users/:user/followers
12+
13+
List the authenticated user's followers:
14+
1015
GET /user/followers
1116

1217
### Response
1318

1419
<%= headers 200, :pagination => true %>
1520
<%= json(:user) { |h| [h] } %>
1621

17-
## List who a user is following
22+
## List users following another user
23+
24+
List who a user is following:
1825

1926
GET /users/:user/following
27+
28+
List who the authenicated user is following:
29+
2030
GET /user/following
2131

2232
### Response
@@ -30,25 +40,25 @@ title: User Followers API v3 | developer.github.com
3040

3141
### Response
3242

33-
<%= headers 204, :no_response => true %>
43+
<%= headers 204 %>
3444

3545
## Unfollow a user
3646

3747
DELETE /user/following/:user
3848

3949
### Response
4050

41-
<%= headers 204, :no_response => true %>
51+
<%= headers 204 %>
4252

4353
## Check if you are following a user
4454

4555
GET /user/following/:user
4656

4757
### Response if you are following this user
4858

49-
<%= headers 204, :no_response => true %>
59+
<%= headers 204 %>
5060

5161
### Response if you are not following this user
5262

53-
<%= headers 404, :no_response => true %>
63+
<%= headers 404 %>
5464

‎content/v3/users/keys.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,11 @@ title: User Public Keys API v3 | developer.github.com
33
---
44

55
# User Public Keys API
6+
67
Management of public keys via the API requires that you are
78
authenticated.
89

9-
## List public keys
10+
## List public keys for a user
1011

1112
GET /user/keys
1213

@@ -15,7 +16,7 @@ authenticated.
1516
<%= headers 200 %>
1617
<%= json(:public_key) { |h| [h] } %>
1718

18-
## Get a public key
19+
## Get a single public key
1920

2021
GET /user/keys/:id
2122

@@ -34,7 +35,7 @@ authenticated.
3435

3536
### Response
3637

37-
<%= headers 201 %>
38+
<%= headers 201, :Location => "https://api.github.com/user/keys/1" %>
3839
<%= json :public_key %>
3940

4041
## Update a public key
@@ -56,5 +57,5 @@ authenticated.
5657

5758
### Response
5859

59-
<%= headers 204, :no_response => true %>
60+
<%= headers 204 %>
6061

0 commit comments

Comments
 (0)