Skip to content

Commit

Permalink
Host Javascript API docs (close #1255)
Browse files Browse the repository at this point in the history
PR #1256
* Add docs workflow
* Remove old docs folder
* Update publish workflow
  • Loading branch information
Jack-Keene authored Nov 28, 2023
1 parent a6f9931 commit b814e59
Show file tree
Hide file tree
Showing 346 changed files with 15,271 additions and 19 deletions.
31 changes: 31 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Deploy to GitHub Pages

on:
workflow_run:
workflows: ['Deploy Tracker']
types:
- completed
permissions:
contents: write

jobs:
deploy:
name: Deploy to GitHub Pages
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18

- name: Install dependencies
working-directory: ./api-docs
run: npm install
- name: Build website
working-directory: ./api-docs
run: npm run build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./api-docs/build
8 changes: 4 additions & 4 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,18 +67,18 @@ jobs:
working-directory: ./trackers/browser-tracker
run: |
api-extractor run
api-documenter markdown --input-folder temp --output-folder docs/markdown
api-documenter markdown --input-folder temp --output-folder ../../api-docs/docs/browser-tracker/markdown
- name: Create API documentation for @snowplow/node-tracker
working-directory: ./trackers/node-tracker
run: |
api-extractor run
api-documenter markdown --input-folder temp --output-folder docs/markdown
api-documenter markdown --input-folder temp --output-folder ../../api-docs/docs/node-tracker/markdown
- name: Apply API documentation updates
run: |
git add trackers/browser-tracker/docs
git add trackers/node-tracker/docs
git add api-docs/docs/browser-tracker
git add api-docs/docs/node-tracker
git commit --no-verify --allow-empty -m "Applying documentation updates."
git push
Expand Down
20 changes: 20 additions & 0 deletions api-docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
3 changes: 3 additions & 0 deletions api-docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
22 changes: 22 additions & 0 deletions api-docs/docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
sidebar_position: 1
---

# JavaScript Trackers
The Snowplow JavaScript Trackers support being used in a number of environments. There are three versions of the tracker.

## Web tracking
We have two flavours of web tracker: JavaScript and Browser.

- JavaScript Tracker (v2 and v3) for loading via tags, by adding code snippets to your website or Tag Manager solution.
- Browser Tracker (v3) for installation into web apps via npm. Popular when natively integrating tracking into React, Angular and Vue applications.

Find the documentation for both in the [Web trackers](https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/) section.


## Server-side tracking
Track events in server-side Node.js environments using the Node.js Tracker (v3). Used via npm.

Find the documentation in the [Node.js tracker](https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/node-js-tracker) section.


Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ declare function buildConsentGranted(event: ConsentGrantedEvent): {

<b>Returns:</b>

{ event: PayloadBuilder; context: { schema: string; data: Record&lt;string, unknown&gt;; }\[\]; }
`{ event: PayloadBuilder; context: { schema: string; data: Record&lt;string, unknown&gt;; }\[\]; }`

An object containing the PayloadBuilder to be sent to and a 'consent\_document' context

Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ declare function buildConsentWithdrawn(event: ConsentWithdrawnEvent): {

<b>Returns:</b>

{ event: PayloadBuilder; context: { schema: string; data: Record&lt;string, unknown&gt;; }\[\]; }
`{ event: PayloadBuilder; context: { schema: string; data: Record&lt;string, unknown&gt;; }\[\]; }`

An object containing the PayloadBuilder to be sent to and a 'consent\_document' context

Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## buildLinkClick() function

Build a Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag <a>
Build a Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag `<a>`

<b>Signature:</b>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## LinkClickEvent interface

A Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag <a>
A Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag `<a>`

<b>Signature:</b>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
| [buildEcommerceTransactionItem(event)](./node-tracker.buildecommercetransactionitem.md) | Build an Ecommerce Transaction Item Event Related to the [buildEcommerceTransaction()](./node-tracker.buildecommercetransaction.md) Each Ecommerce Transaction may contain one or more EcommerceTransactionItem events |
| [buildFormFocusOrChange(event)](./node-tracker.buildformfocusorchange.md) | Build a Form Focus or Change Form Event based on schema property When a user focuses on a form element or when a user makes a change to a form element. |
| [buildFormSubmission(event)](./node-tracker.buildformsubmission.md) | Build a Form Submission Event Used to track when a user submits a form |
| [buildLinkClick(event)](./node-tracker.buildlinkclick.md) | Build a Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag <a> |
| [buildLinkClick(event)](./node-tracker.buildlinkclick.md) | Build a Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag `<a>` |
| [buildPagePing(event)](./node-tracker.buildpageping.md) | Build a Page Ping Event Fires when activity tracking is enabled in the browser. Tracks same information as the last tracked Page View and includes scroll information from the current page view |
| [buildPageView(event)](./node-tracker.buildpageview.md) | Build a Page View Event Represents a Page View, which is typically fired as soon as possible when a web page is loaded within the users browser. Often also fired on "virtual page views" within Single Page Applications (SPA). |
| [buildRemoveFromCart(event)](./node-tracker.buildremovefromcart.md) | Build a Remove From Cart Event For tracking users removing items from a cart on an ecommerce site. |
Expand Down Expand Up @@ -55,7 +55,7 @@
| [Emitter](./node-tracker.emitter.md) | |
| [FormFocusOrChangeEvent](./node-tracker.formfocusorchangeevent.md) | Represents either a Form Focus or Form Change event When a user focuses on a form element or when a user makes a change to a form element. |
| [FormSubmissionEvent](./node-tracker.formsubmissionevent.md) | A Form Submission Event Used to track when a user submits a form |
| [LinkClickEvent](./node-tracker.linkclickevent.md) | A Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag <a> |
| [LinkClickEvent](./node-tracker.linkclickevent.md) | A Link Click Event Used when a user clicks on a link on a webpage, typically an anchor tag `<a>` |
| [PagePingEvent](./node-tracker.pagepingevent.md) | A Page Ping Event Fires when activity tracking is enabled in the browser. Tracks same information as the last tracked Page View and includes scroll information from the current page view |
| [PageViewEvent](./node-tracker.pageviewevent.md) | A Page View Event Represents a Page View, which is typically fired as soon as possible when a web page is loaded within the users browser. Often also fired on "virtual page views" within Single Page Applications (SPA). |
| [PayloadBuilder](./node-tracker.payloadbuilder.md) | Interface for mutable object encapsulating tracker payload |
Expand All @@ -80,6 +80,6 @@
| [ContextFilter](./node-tracker.contextfilter.md) | A context filter is a user-supplied callback that is evaluated for each event to determine if the context associated with the filter should be attached to the event |
| [ContextGenerator](./node-tracker.contextgenerator.md) | A context generator is a user-supplied callback that is evaluated for each event to allow an additional context to be dynamically attached to the event |
| [Payload](./node-tracker.payload.md) | Type for a Payload dictionary |
| [SelfDescribingJson](./node-tracker.selfdescribingjson.md) | export interface for any Self-Describing JSON such as context or Self Describing events |
| [SelfDescribingJson](./node-tracker.selfdescribingjson.md) | Export interface for any Self-Describing JSON such as context or Self Describing events |
| [Timestamp](./node-tracker.timestamp.md) | Algebraic datatype representing possible timestamp type choice |

Loading

0 comments on commit b814e59

Please sign in to comment.