Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Host Javascript API docs (close #1255) #1256

Merged
merged 36 commits into from
Nov 28, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
0df4f2f
Test deploy to gh pages
Jack-Keene Oct 20, 2023
758ff94
Add docs workflow
Jack-Keene Oct 20, 2023
a7123b4
Fix docs wf
Jack-Keene Oct 20, 2023
ed52127
Fix docs wf
Jack-Keene Oct 20, 2023
3cc09a3
test
Jack-Keene Oct 20, 2023
93e581b
test folder
Jack-Keene Oct 20, 2023
3dbc029
test folder
Jack-Keene Oct 20, 2023
b6210a6
test folder
Jack-Keene Oct 20, 2023
a80eb83
test folder
Jack-Keene Nov 22, 2023
cfacc84
Test new action
Jack-Keene Nov 24, 2023
58df59e
add second folder
Jack-Keene Nov 24, 2023
01e2f8d
add second folder
Jack-Keene Nov 24, 2023
5d82cfa
UPdate workflow
Jack-Keene Nov 27, 2023
58cdbc1
Add docusaurus
Jack-Keene Nov 27, 2023
0432195
Change working directory
Jack-Keene Nov 27, 2023
7082d89
use npm
Jack-Keene Nov 27, 2023
604bfec
remove cache
Jack-Keene Nov 27, 2023
32d391e
update build command
Jack-Keene Nov 27, 2023
28ca73d
update broken link
Jack-Keene Nov 27, 2023
125bd13
update broken link
Jack-Keene Nov 27, 2023
f6d0486
update folder
Jack-Keene Nov 27, 2023
97a82bf
update api docs output folder
Jack-Keene Nov 27, 2023
61b16a5
Update configs
Jack-Keene Nov 27, 2023
0240243
Remove old docs folder
Jack-Keene Nov 27, 2023
900b0b6
Add search
Jack-Keene Nov 27, 2023
e53a5d8
Update api key
Jack-Keene Nov 27, 2023
975876e
Review comments
Jack-Keene Nov 27, 2023
0b1edcc
remove comments
Jack-Keene Nov 27, 2023
509746e
escape inline js
Jack-Keene Nov 27, 2023
e6ae71c
Update publish workflow
Jack-Keene Nov 27, 2023
8cf07b7
Add links to js docs
Jack-Keene Nov 27, 2023
7a2c8a4
Add links to js docs
Jack-Keene Nov 27, 2023
38c7bfa
Update workflow
Jack-Keene Nov 27, 2023
22d6582
Rush change
Jack-Keene Nov 28, 2023
be80a9d
update output folder
Jack-Keene Nov 28, 2023
95ff862
update report folder for api extractor
Jack-Keene Nov 28, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
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.
Jack-Keene marked this conversation as resolved.
Show resolved Hide resolved

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
Loading