Skip to content

Commit

Permalink
chore(docs): adding analytics (AztecProtocol#6350)
Browse files Browse the repository at this point in the history
  • Loading branch information
signorecello authored May 16, 2024
1 parent 29559bd commit 6417cd9
Show file tree
Hide file tree
Showing 10 changed files with 998 additions and 1,182 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ jobs:
concurrency_key: docs-preview-x86
- name: "Docs Preview"
timeout-minutes: 40
run: earthly-ci --no-output ./docs/+deploy-preview --PR=${{ github.event.number }} --AZTEC_BOT_COMMENTER_GITHUB_TOKEN=${{ secrets.AZTEC_BOT_GITHUB_TOKEN }} --NETLIFY_AUTH_TOKEN=${{ secrets.NETLIFY_AUTH_TOKEN }} --NETLIFY_SITE_ID=${{ secrets.NETLIFY_SITE_ID }}
run: earthly-ci --no-output ./docs/+deploy-preview --ENV=staging --PR=${{ github.event.number }} --AZTEC_BOT_COMMENTER_GITHUB_TOKEN=${{ secrets.AZTEC_BOT_GITHUB_TOKEN }} --NETLIFY_AUTH_TOKEN=${{ secrets.NETLIFY_AUTH_TOKEN }} --NETLIFY_SITE_ID=${{ secrets.NETLIFY_SITE_ID }}

bb-bench:
runs-on: ubuntu-latest
Expand Down
7 changes: 4 additions & 3 deletions docs/Earthfile
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,18 @@ deps:
RUN yarn install --frozen-lockfile

build:
ARG ENV
BUILD ../yarn-project/+build-dev
BUILD ../+release-meta
FROM +deps

COPY --dir ../yarn-project/+build-dev/usr/src /usr
COPY ../+release-meta/usr/src/.release-please-manifest.json /usr/src

COPY . .

RUN ./scripts/build.sh
SAVE ARTIFACT build

serve:
ARG ENV
FROM +deps
COPY +build/build build
COPY ./static static
Expand All @@ -34,8 +33,10 @@ serve:
SAVE ARTIFACT /usr/src/docs
SAVE IMAGE aztecprotocol/docs-server


deploy-preview:
BUILD ../yarn-project/+scripts-prod
ARG ENV
ARG NETLIFY_AUTH_TOKEN
ARG NETLIFY_SITE_ID
ARG AZTEC_BOT_COMMENTER_GITHUB_TOKEN
Expand Down
59 changes: 39 additions & 20 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,13 @@ Documentation for the Aztec Network, built with docusaurus

You can view the latest successful build here: https://docs.aztec.network

## Files
## Docusaurus

This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.

### Files

Here are the most relevant files you should be aware of:

- `.gitignore` - This specifies which files Git should ignore when committing and pushing to remote repositories.
- `docusaurus.config.js` - This is the configuration file for Docusaurus. You can manage the links in the header and footer, and site metadata here. A more in-depth introduction to this configuration file is available on the [Docusaurus website](https://docusaurus.io/docs/configuration) and full documentation for the API is [here](https://docusaurus.io/docs/docusaurus.config.js).
Expand All @@ -15,52 +21,61 @@ You can view the latest successful build here: https://docs.aztec.network

The .md files in the `docs/` directory are the docs. See the [Docusaurus website](https://docusaurus.io/docs/docs-introduction) for the full documentation on how to create docs and to manage the metadata.

## Contributing

We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.

## Docusaurus

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.

### Installation

To install the dependencies and dev dependencies, run:

```
$ yarn
```

### Development

#### Locally
Aztec docs pull some code from the rest of the repository. This allows for great flexibility and maintainability. Some documentation is also autogenerated.

For that reason, there's a preprocessing step. You can run that step ad-hoc with `yarn preprocess` or `yarn preprocess:dev` if you want it to stay running and watching for changes.

To build; serve to `localhost:3000`; and watch for changes:
This step does the following:
- Pulls the code from the source files using the `#include` macros explained below.
- Autogenerates documentation using the scripts in the `src` file.
- Puts the final documentation in a `processed-docs` folder.

> [!NOTE]
> You likely want to benefit from webpack's hot reload, which allows you to immediately see your changes when you develop on the docs. For this reason, the `yarn dev` commands will add the `ENV=dev` environment variable, which makes docusaurus serve the `docs folder` instead of the `processed docs`.
> If you're making changes to included code or aztec.nr reference, you can run `yarn docs` instead.
#### Run locally

To run docusaurus development server and use hot reload (watch for changes), run:

```
$ yarn start:dev:local
$ yarn dev:local
```

#### Remotely (on mainframe)
#### Run remotely (on mainframe)

To build; serve to `localhost:3000`; and watch for changes:
It's common for developers to work on codespaces or other remote targets. For this you need to expose your development server. This is common enough to be the default development command:

```
$ yarn start:dev
$ yarn dev
```

This command preprocesses `#include_code` macros, then builds the html, then starts a local development server and opens up a browser window (at `localhost:3000`, by default).
Most changes are reflected live without having to restart the server.

### Build

To build the final version of the docs (which includes processes not present in dev, like broken links checking and minification), you can run:

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service. When run on Netlify, it will also build the typescript projects needed for extracting type information via typedoc.

This command runs the preprocess command, generates static content into the `build` directory and can be served using any static contents hosting service.

## Macros

As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.

This is done via macros which are processed in the `process` step described above.

### `#include_code`

You can embed code snippets into a `.md`/`.mdx` file from code which lives elsewhere in the repo.
Expand Down Expand Up @@ -133,3 +148,7 @@ Alternatively, you can also use the `AztecPackagesVersion()` js function, which
import { AztecPackagesVersion } from "@site/src/components/Version";
<>{AztecPackagesVersion()}</>
```
## Contributing
We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.
3 changes: 3 additions & 0 deletions docs/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,9 @@ const config = {
],
// ["./src/plugins/plugin-embed-code", {}],
],
customFields: {
MATOMO_ENV: process.env.ENV,
},
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
Expand Down
8 changes: 3 additions & 5 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,11 @@
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "yarn preprocess && yarn typedoc && docusaurus start --host 0.0.0.0",
"start:dev": "ENV=dev yarn start",
"start:dev:local": "yarn preprocess && yarn typedoc && docusaurus start",
"docs": "yarn preprocess && yarn typedoc && docusaurus start --host ${HOST:-localhost}",
"dev": "HOST=0.0.0.0 ENV=dev yarn docs",
"dev:local": "ENV=dev yarn docs",
"build": "./scripts/build.sh",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "rm -rf 'processed-docs' 'processed-docs-cache' docs/apis && docusaurus clear && rm 'src/preprocess/AztecnrReferenceAutogenStructure.json' && rm -rf 'docs/developers/references/aztec-nr'",
"serve": "docusaurus serve",
"preprocess": "yarn node -r dotenv/config ./src/preprocess/index.js && node src/preprocess/generate_aztecnr_reference.js",
Expand Down
3 changes: 3 additions & 0 deletions docs/scripts/build.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
#!/usr/bin/env bash
set -eo pipefail

echo "Running with ENV set to: $ENV"

# Helper function for building packages in yarn project
build_package() {
local package_name="$1"
Expand Down Expand Up @@ -48,4 +50,5 @@ echo Building docsite...
echo "Generating Aztec.nr reference docs..."
node ./src/preprocess/generate_aztecnr_reference.js
echo "Generated Aztec.nr reference docs"

yarn preprocess && yarn typedoc && yarn docusaurus build
151 changes: 151 additions & 0 deletions docs/src/components/Matomo/matomo.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
import { useEffect, useState } from "react";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import Link from "@docusaurus/Link";
import { useLocation } from "@docusaurus/router";

function getSiteId(env) {
if (env == "dev") {
return "4";
} else if (env == "staging") {
return "5";
} else {
return "6";
}
}
function pushInstruction(name, ...args) {
return window._paq.push([name, ...args]);
}

export default function useMatomo() {
const { siteConfig } = useDocusaurusContext();
const [showBanner, setShowBanner] = useState(false);
const location = useLocation();

const env = siteConfig.customFields.MATOMO_ENV;
const urlBase = "https://noirlang.matomo.cloud/";
const trackerUrl = `${urlBase}matomo.php`;
const srcUrl = `${urlBase}matomo.js`;

window._paq = window._paq || [];

useEffect(() => {
const storedConsent = localStorage.getItem("matomoConsent");
if (storedConsent === null) {
setShowBanner(true);
}
}, []);

useEffect(() => {
pushInstruction("setTrackerUrl", trackerUrl);
pushInstruction("setSiteId", getSiteId(env));
if (env !== "prod") {
pushInstruction("setSecureCookie", false);
}

const doc = document;
const scriptElement = doc.createElement("script");
const scripts = doc.getElementsByTagName("script")[0];

scriptElement.type = "text/javascript";
scriptElement.async = true;
scriptElement.defer = true;
scriptElement.src = srcUrl;

if (scripts && scripts.parentNode) {
scripts.parentNode.insertBefore(scriptElement, scripts);
}
}, []);

useEffect(() => {
pushInstruction("trackPageView");
}, [location]);

const optIn = () => {
pushInstruction("rememberConsentGiven");
localStorage.setItem("matomoConsent", true);
setShowBanner(false);
};

const optOut = () => {
pushInstruction("forgetConsentGiven");
localStorage.setItem("matomoConsent", false);
setShowBanner(false);
};

const debug = () => {
pushInstruction(function () {
console.log(this.getRememberedConsent());
console.log(localStorage.getItem("matomoConsent"));
});
};

const reset = () => {
pushInstruction("forgetConsentGiven");
localStorage.clear("matomoConsent");
};

if (!showBanner && env === "dev") {
return (
<div id="optout-form">
<div className="homepage_footer">
<p>Debugging analytics</p>
<div className="homepage_cta_footer_container">
<button
className="cta-button button button--secondary button--sm"
onClick={debug}
>
Debug
</button>
<button
className="cta-button button button--secondary button--sm"
onClick={reset}
>
Reset
</button>
</div>
</div>
</div>
);
} else if (!showBanner) {
return null;
}

return (
<div id="optout-form">
<div className="homepage_footer">
<p>
We value your privacy and we only collect statistics and essential
cookies. If you'd like to help us improve our websites, you can allow
cookies for tracking page views, time on site, and other analytics.
<br />
<br />
<Link to="https://aztec.network/privacy-policy/">
Find out how we use cookies and how you can change your settings.
</Link>
</p>
<div className="homepage_cta_footer_container">
<button
className="cta-button button button--primary button--sm"
onClick={optIn}
>
I accept cookies
</button>
<button
className="cta-button button button--secondary button--sm"
onClick={optOut}
>
I refuse cookies
</button>
{env === "dev" && (
<button
className="cta-button button button--secondary button--sm"
onClick={debug}
>
Debug
</button>
)}
</div>
</div>
</div>
);
}
Loading

0 comments on commit 6417cd9

Please sign in to comment.