Re-add reference documentation

.github/maintainers_guide.md

@@ -22,9 +22,9 @@ and to allow lerna to link them to each other.
 ### Testing
 
 This project has tests for individual packages inside of each's respective `test` directory. It also has
-integration tests in the `integration-tests` directory at the root. You can run the entire test suite using the npm
-script `npm test` at the top level. This script will use Lerna to invoke tests in each package and the integration
-tests.
+integration tests in the `integration-tests` directory under the root `support` directory. You can run the entire test
+suite using the npm script `npm test` at the top level. This script will use Lerna to invoke tests in each package and
+the integration tests.
 
 Tests are executed by Travis, our continuous integration system, slightly differently. Travis runs several, more
 granular builds in order to report on success and failure in a more useful (targeted) way. There is one build for each
@@ -44,9 +44,15 @@ We have included `launch.json` files that store configuration for `vscode` debug
 
 The documentation is built using [Jekyll](https://jekyllrb.com/) and hosted with GitHub Pages. The source files are
 contained in the `docs` directory. Reading the Jekyll configuration in `docs/_config.yml` is helpful to understand how
-the documentation is organized and built.
+the documentation is organized and built. To build the docs, you will have to run the command `bundle exec jekyll serve` 
+in the docs directory. A prerequisite to building the docs locally is to have ruby ~2.5.3 and install the dependencies by running `bundle install`.
 
-**TODO** add information regarding building reference documentation, once that process is revised.
+To build reference documentation, in the root of this repo, run `npm run ref-docs`. This will generate reference docs and put them in the `docs/_reference` directory.
+Currently, reference docs need to be built manually running this command and checked into GitHub.
+
+**TODO**: Update this doc once building of reference docs is automated to happen on each commit to the repo
+
+Reference docs are built by using various open source tools and formats. This includes [API-Extractor](https://api-extractor.com/), [mdast](https://github.com/syntax-tree/mdast), and [Remark](https://github.com/remarkjs/remark). [Read more about the reference docs pipeline](https://github.com/slackapi/node-slack-sdk/pull/831#issue-299509206).
 
 ### Releasing
 

docs/.gitignore

@@ -1,3 +1,6 @@
 _site
 Gemfile.lock
 .env
+
+# Built reference docs need to be committed currently
+# /_reference/*.md

docs/_config.yml

@@ -21,6 +21,9 @@ collections:
   tutorials:
     output: true
     permalink: /tutorials/:slug
+  reference:
+    output: true
+    permalink: /reference/:slug
 
 defaults:
   -
@@ -41,6 +44,12 @@ defaults:
       type: tutorials
     values:
       layout: contained
+  -
+    scope:
+      path: ""
+      type: reference
+    values:
+      layout: contained
 
 baseurl: /node-slack-sdk
 url: https://slack.dev

docs/_includes/main_nav.html

@@ -14,6 +14,8 @@ <h4 class="sidebar_menu_header">Packages</h4>
         {% for doc in packages %}
             <li><a href="{{ doc.url | prepend: site.baseurl }}" class="sidebar_menu_list_item">{{ doc.title }}</a></li>
         {% endfor %}
+
+        <li><a href="{{ '/reference/' | prepend: site.baseurl }}" class="sidebar_menu_list_item">Reference</a></li>
     </ul>
 </div>
 

docs/_layouts/contained.html

@@ -1,6 +1,6 @@
 ---
 layout: default
-sidebar_style: focussed
+sidebar_style: focused
 ---
 
 {{ content }}

docs/_layouts/default.html

@@ -18,8 +18,8 @@
             {% case layout.sidebar_style %}
                 {% when 'main' %}
                     {% include main_nav.html %}
-                {% when 'focussed' %}
-                    {% include focussed_nav.html %}
+                {% when 'focused' %}
+                    {% include focused_nav.html %}
             {% endcase %}
 
             <div class="sidebar_menu">

docs/_reference/events-api.md

@@ -0,0 +1,308 @@
+---
+title: "@slack/events-api"
+slug: events-api
+---
+
+<h1 id="classes" class="undefined auto-anchor-strong">Classes</h1>
+<h2 id="slackeventadapter">SlackEventAdapter</h2>
+<p>An adapter for Slack's Events API.</p>
+<h4>new SlackEventAdapter(signingSecret, opts)</h4>
+<p>Constructs a new instance of the <code>SlackEventAdapter</code> class</p>
+<strong>Parameters:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th align="center">Required</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">signingSecret</td>
+<td align="center"><code>string</code></td>
+<td align="center">✓</td>
+<td><p>The token used to authenticate signed requests from Slack's Events API.</p></td>
+</tr>
+<tr>
+<td align="center">opts</td>
+<td align="center"><code><a href="#eventadapteroptions" title="">EventAdapterOptions</a></code></td>
+<td align="center">✗</td>
+<td>See options.</td>
+</tr>
+</tbody>
+</table>
+<strong>Options:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">includeBody</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+<tr>
+<td align="center">includeHeaders</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+<tr>
+<td align="center">waitForResponse</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<h3>Fields</h3>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">includeBody</td>
+<td align="center"><code>boolean</code></td>
+<td><p>Whether to include the API event bodies in adapter event listeners.</p></td>
+</tr>
+<tr>
+<td align="center">includeHeaders</td>
+<td align="center"><code>boolean</code></td>
+<td><p>Whether to include request headers in adapter event listeners.</p></td>
+</tr>
+<tr>
+<td align="center">signingSecret</td>
+<td align="center"><code>string</code></td>
+<td><p>The token used to authenticate signed requests from Slack's Events API.</p></td>
+</tr>
+<tr>
+<td align="center">waitForResponse</td>
+<td align="center"><code>boolean</code></td>
+<td><p>When <code>true</code> prevents the adapter from responding by itself and leaves that up to listeners.</p></td>
+</tr>
+</tbody>
+</table>
+<h3>Methods</h3>
+<h4>createServer()</h4>
+<p>Creates an HTTP server to listen for event payloads.</p>
+<p><strong>Returns</strong> <code>Promise&#x3C;http.Server></code></p>
+<h4>expressMiddleware()</h4>
+<p>Returns a middleware-compatible adapter.</p>
+<p><strong>Returns</strong> <code>RequestHandler</code></p>
+<h4>requestListener()</h4>
+<p>Creates a request listener.</p>
+<p><strong>Returns</strong> <code>RequestListener</code></p>
+<h4>start(port)</h4>
+<p>Starts a server on the specified port.</p>
+<strong>Parameters:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th align="center">Required</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">port</td>
+<td align="center"><code>number</code></td>
+<td align="center">✓</td>
+<td><p>The port number to listen on.</p></td>
+</tr>
+</tbody>
+</table>
+<p><strong>Returns</strong> <code>Promise&#x3C;http.Server></code></p>
+<h4>stop()</h4>
+<p>Stops the server started by <a href="#slackeventadapter" title=""><code>SlackEventAdapter</code></a>.</p>
+<p><strong>Returns</strong> <code>Promise&#x3C;void></code></p>
+<h1 id="functions" class="undefined auto-anchor-strong">Functions</h1>
+<h2 id="createeventadapter-signingsecret-options-">createEventAdapter(signingSecret, options)</h2>
+<p>Creates a new <a href="#slackeventadapter" title=""><code>SlackEventAdapter</code></a>.</p>
+<strong>Parameters:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th align="center">Required</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">signingSecret</td>
+<td align="center"><code>string</code></td>
+<td align="center">✓</td>
+<td></td>
+</tr>
+<tr>
+<td align="center">options</td>
+<td align="center"><code><a href="#eventadapteroptions" title="">EventAdapterOptions</a></code></td>
+<td align="center">✗</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p><strong>Returns</strong> <code><a href="#slackeventadapter" title="">SlackEventAdapter</a></code></p>
+<h2 id="verifyrequestsignature-opts-">verifyRequestSignature(opts)</h2>
+<p>Verifies the signature of a request. Throws a <a href="#codederror" title=""><code>CodedError</code></a> if the signature is invalid.</p>
+<h5>Remarks</h5>
+<p>See [Verifying requests from Slack](https://api.slack.com/docs/verifying-requests-from-slack#sdk_support) for more information.</p>
+<strong>Parameters:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th align="center">Required</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">opts</td>
+<td align="center"><code><a href="#verifyrequestsignatureparams" title="">VerifyRequestSignatureParams</a></code></td>
+<td align="center">✓</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<strong>Options:</strong>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">body</td>
+<td align="center"><code>string</code></td>
+<td><p>Full, raw body string.</p></td>
+</tr>
+<tr>
+<td align="center">requestSignature</td>
+<td align="center"><code>string</code></td>
+<td><p>Signature from the <code>X-Slack-Signature</code> header.</p></td>
+</tr>
+<tr>
+<td align="center">requestTimestamp</td>
+<td align="center"><code>number</code></td>
+<td><p>Timestamp from the <code>X-Slack-Request-Timestamp</code> header.</p></td>
+</tr>
+<tr>
+<td align="center">signingSecret</td>
+<td align="center"><code>string</code></td>
+<td><p>The signing secret used to verify request signature.</p></td>
+</tr>
+</tbody>
+</table>
+<p><strong>Returns</strong> <code>true</code>:<br>
+<br>
+<code>true</code> when the signature is valid.</p>
+<h1 id="enums" class="undefined auto-anchor-strong">Enums</h1>
+<h2 id="errorcode">ErrorCode</h2>
+<p>A dictionary of codes for errors produced by this package.</p>
+<h3>Members</h3>
+<ul>
+<li><strong>BodyParserNotPermitted</strong></li>
+<li><strong>RequestTimeFailure</strong></li>
+<li><strong>SignatureVerificationFailure</strong></li>
+</ul>
+<h1 id="interfaces" class="undefined auto-anchor-strong">Interfaces</h1>
+<h2 id="codederror">CodedError</h2>
+<p>All errors produced by this package are regular <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" title="">Error</a> objects with an extra <a href="#codederror" title=""><code>CodedError</code></a> field.</p>
+<h3>Fields</h3>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">code</td>
+<td align="center"><code><a href="#errorcode" title="">ErrorCode</a></code></td>
+<td><p>What kind of error occurred.</p></td>
+</tr>
+</tbody>
+</table>
+<h2 id="eventadapteroptions">EventAdapterOptions</h2>
+<p>Options when constructing <a href="#slackeventadapter" title=""><code>SlackEventAdapter</code></a>. See <a href="#slackeventadapter" title=""><code>SlackEventAdapter</code></a>'s fields for more information on what each option does.</p>
+<h3>Fields</h3>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">includeBody</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+<tr>
+<td align="center">includeHeaders</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+<tr>
+<td align="center">waitForResponse</td>
+<td align="center"><code>boolean</code></td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<h2 id="verifyrequestsignatureparams">VerifyRequestSignatureParams</h2>
+<p>Parameters for calling <a href="#verifyrequestsignature" title=""><code>verifyRequestSignature</code></a>.</p>
+<h3>Fields</h3>
+<table>
+<thead>
+<tr>
+<th align="center">Name</th>
+<th align="center">Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">body</td>
+<td align="center"><code>string</code></td>
+<td><p>Full, raw body string.</p></td>
+</tr>
+<tr>
+<td align="center">requestSignature</td>
+<td align="center"><code>string</code></td>
+<td><p>Signature from the <code>X-Slack-Signature</code> header.</p></td>
+</tr>
+<tr>
+<td align="center">requestTimestamp</td>
+<td align="center"><code>number</code></td>
+<td><p>Timestamp from the <code>X-Slack-Request-Timestamp</code> header.</p></td>
+</tr>
+<tr>
+<td align="center">signingSecret</td>
+<td align="center"><code>string</code></td>
+<td><p>The signing secret used to verify request signature.</p></td>
+</tr>
+</tbody>
+</table>