Skip to content

Commit 268fbc4

Browse files
SimonWoolfSimonWoolf
authored
Merge pull request #261 from ably/add-api-reference
Port api reference to specification repo
2 parents cc6c60f + 64b2746 commit 268fbc4

3 files changed

Lines changed: 1249 additions & 8 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,74 @@ Historically, before the above guidance was established - in particular around _
6565
This left us open to the problem that client library references to spec items could end up semantically invalid if that spec point was re-used later.
6666
For example, if `XXX1a` and `XXX1c` exist but `XXX1b` doesn’t because it was removed in the past (prior to this guidance being established), then we should introduce `XXX1d` for the new spec item rather than re-using `XXX1b`.
6767

68+
## SDK API docstrings
69+
70+
The `api-docstrings.md` file is a set of language-agnostic reference API commentaries for SDK developers to use when adding docstring comments to Ably SDKs. For new fields, this file should be modified in the same PR that makes the spec changes for those fields.
71+
72+
Modifications should obey the following conventions:
73+
74+
### Table format
75+
76+
#### Classes
77+
78+
The table for each class contains the following columns:
79+
80+
```
81+
| Method / Property | Parameter | Returns | Spec | Description |
82+
```
83+
84+
* **Method/Property**: The full method signature (code formatted only where necessary, e.g. where it includes `<`, or property name.
85+
* **Parameter**: Each parameter should have its own row and be code formatted.
86+
* **Returns**: The return value should be code formatted and has its own row, after the parameters have been listed.
87+
* **Spec**: The spec point related to the method or property.
88+
* **Description**: The language-agnostic description that will form the docstrings.
89+
90+
#### Enums
91+
92+
The table for each enum contains the following columns:
93+
94+
```markdown
95+
| Enum | Spec | Description |
96+
```
97+
98+
* **Enum**: The name of each value for the enum.
99+
* **Spec**: The spec point related to the enum.
100+
* **Description**: The language-agnostic description that will form the docstrings.
101+
102+
### Conventions
103+
104+
The following conventions should be followed when adding a new method or property to the table:
105+
106+
* Use a verb with an `s` for method descriptions. Common uses are:
107+
* `get` --> `retrieves`
108+
* `subscribe` --> `registers (a listener)`
109+
* `publish` --> `Publishes`
110+
* The expression key-value pairs should be hyphenated.
111+
* Parameters or returns that refer to another class are referred to in terms of objects, for example:
112+
```
113+
A [`Channels`]{@link Channels} object.
114+
```
115+
116+
* Links to other classes/enums are written in the format:
117+
```
118+
[`<text>`]{@link <class>#<property>}
119+
```
120+
121+
For example:
122+
```
123+
[`ClientOptions.logLevel`]{@link ClientOptions#logLevel}`
124+
```
125+
* If a method references its own class, it should just be code formatted, and not link to itself.
126+
* Descriptions can link out to conceptual docs hosted on `ably.com/docs`, but should never link to the API references hosted there.
127+
* A class or object should always be capitalized.
128+
* Methods and parameters should always be lower-case.
129+
* If adding a method/property to separate REST and realtime classes, ensure the descriptions are consistent (where possible).
130+
* When a return value is returned in a paginated list, the description should link to the PaginatedResult class, as well as the class of whatever is returned.
131+
* Items deprecated in the features spec should include the following text at the beginning of the description: `DEPRECATED: this <property/method> is deprecated and will be removed in a future version.`
132+
* Default values should be listed in the description field.
133+
* If a minimum or maximum value exists for a parameter then it should be listed in the description field.
134+
* Time values should be referred to as `milliseconds since the Unix epoch` where applicable.
135+
68136
## Release Process
69137
70138
Use our standard [Release Process](https://github.com/ably/engineering/blob/main/sdk/releases.md#release-process), where:

‎scripts/build‎

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@ gemfile do
77
source 'https://rubygems.org'
88
gem 'RedCloth', '~> 4.3.2'
99
gem 'ruby-handlebars', '~> 0.4.1'
10+
gem 'kramdown', '~> 2.4.0'
1011
end
1112
puts 'Gems installed and loaded.'
1213

1314
SOURCE_PATH = File.expand_path('../../textile', __FILE__)
14-
SOURCE_EXTENSION = '.textile'
15+
TEXTILE_EXTENSION = '.textile'
16+
MARKDOWN_EXTENSION = '.md'
1517
ROOT_SOURCE_NAME = 'index'
1618
TEMPLATE_PATH = File.expand_path('../../templates/docs-textile.html.hbs', __FILE__)
1719
OUTPUT_PATH = File.expand_path('../../output', __FILE__)
@@ -77,16 +79,19 @@ versions = YAML.load_file(META_PATH)['versions']
7779
handlebars = Handlebars::Handlebars.new
7880
template = handlebars.compile(File.read(TEMPLATE_PATH))
7981

80-
source_file_names = Dir.children(SOURCE_PATH).select {
81-
|file_name| file_name.end_with? "#{SOURCE_EXTENSION}"
82+
textile_file_names = Dir.children(SOURCE_PATH).select {
83+
|file_name| file_name.end_with? "#{TEXTILE_EXTENSION}"
8284
}.sort
8385

84-
# File names without '.textile' extension, and without the root 'index'.
85-
plain_file_names = source_file_names.collect {
86-
|file_name| file_name.delete_suffix(SOURCE_EXTENSION)
86+
markdown_file_names = Dir.children(SOURCE_PATH).select {
87+
|file_name| file_name.end_with? "#{MARKDOWN_EXTENSION}"
88+
}.sort
89+
90+
plain_file_names = (textile_file_names + markdown_file_names).collect {
91+
|file_name| file_name.delete_suffix(TEXTILE_EXTENSION).delete_suffix(MARKDOWN_EXTENSION)
8792
} - [ROOT_SOURCE_NAME]
8893

89-
source_file_names.each do |file_name|
94+
textile_file_names.each do |file_name|
9095
print "#{file_name} ... "
9196

9297
# We could possibly have used the Handlebars gem we're using elsewhere for this, however it was barfing on features.textile for no clear reason.
@@ -96,7 +101,35 @@ source_file_names.each do |file_name|
96101
.gsub(/\{\{\s*PROTOCOL_VERSION\s*\}\}/, versions['protocol'].to_s)
97102

98103
bodyHtml = RedCloth.new(textile, [:no_span_caps]).to_html(*REDCLOTH_RULES)
99-
plain_file_name = file_name.delete_suffix(SOURCE_EXTENSION)
104+
plain_file_name = file_name.delete_suffix(TEXTILE_EXTENSION)
105+
is_root = (plain_file_name == ROOT_SOURCE_NAME)
106+
html = template.call({
107+
bodyContent: bodyHtml,
108+
title: plain_file_name.capitalize(),
109+
file_names: plain_file_names - [plain_file_name],
110+
root_path: is_root ? '' : '../',
111+
copyright: COPYRIGHT,
112+
build_context_title: BUILD_CONTEXT_TITLE,
113+
build_context_url: BUILD_CONTEXT_URL,
114+
build_context_sha: BUILD_CONTEXT_SHA,
115+
})
116+
folder_path = is_root ? OUTPUT_PATH : File.join(OUTPUT_PATH, plain_file_name)
117+
if !is_root
118+
Dir.mkdir folder_path
119+
end
120+
File.write(File.join(folder_path, "index.html"), html)
121+
puts "✓"
122+
end
123+
124+
markdown_file_names.each do |file_name|
125+
print "#{file_name} ... "
126+
127+
markdown_content = remove_frontmatter(File.read(File.join(SOURCE_PATH, file_name)))
128+
.gsub(/\{\{\s*SPECIFICATION_VERSION\s*\}\}/, versions['specification'].to_s)
129+
.gsub(/\{\{\s*PROTOCOL_VERSION\s*\}\}/, versions['protocol'].to_s)
130+
131+
bodyHtml = Kramdown::Document.new(markdown_content).to_html
132+
plain_file_name = file_name.delete_suffix(MARKDOWN_EXTENSION)
100133
is_root = (plain_file_name == ROOT_SOURCE_NAME)
101134
html = template.call({
102135
bodyContent: bodyHtml,

0 commit comments

Comments
 (0)