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

chore(docs): adding analytics #6350

Merged
merged 8 commits into from
May 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds great for visual changes.
Apart from URLs, what is in processed docs that might need to be tested? Might just need a comment with what is not accurate between docs vs processed_docs.
Saw that CI is building staging docs 👍

Copy link
Contributor

@critesjosh critesjosh May 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree that it would be useful to list all of the things that the preprocess step does.

i think its this

  1. injects macro code (#include_code and #include_version)
  2. generates aztec.nr,
  3. generates the instruction set for doc for the public vm protocol spec page

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly, it just adds the autogenerated stuff

> 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice this is here (related to previous comment)


```
$ 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
Loading