docs: refactor documentation structure

docs(structure): refactor website doc to better organize pages
privacy-scaling-explorations · May 17, 2024 · fa8a247 · fa8a247
1 parent 5ca7213
commit fa8a247
Show file tree

Hide file tree

Showing 51 changed files with 163 additions and 103 deletions.
diff --git a/website/.gitignore b/website/.gitignore
@@ -20,5 +20,5 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-versioned_docs/version-v1.3_alpha/typedoc/
-versioned_docs/version-v1.3_alpha/solidity-docs/
+versioned_docs/version-v2.0_alpha/developers-references/typescript-code/typedoc/
+versioned_docs/version-v2.0_alpha/developers-references/smart-contracts/solidity-docs/
diff --git a/website/blog/2023-01-18-maci-v1.1.1.md b/website/blog/2023-01-18-maci-v1.1.1.md
@@ -92,7 +92,7 @@ For further reading on coordinator services, please refer to this [doc](https://
 
 MACI can be used as a standalone application to carry out on-chain polls, or be implemented into new projects that can then benefit from its properties.
 
-For use as a standalone application, a `cli` package is provided which allows coordinators and voters to use MACI. Please refer to this [doc](/docs/cli) for details on how to use it.
+For use as a standalone application, a `cli` package is provided which allows coordinators and voters to use MACI. Please refer to this [doc](/docs/developers-references/typescript-code/cli) for details on how to use it.
 
 To implement MACI into a project, the [documentation](/docs/introduction) can be used a reference, as well as reviewing how [clr.fund](https://github.com/clrfund) and [qf](https://github.com/privacy-scaling-explorations/qf) use MACI in their code.
 

diff --git a/website/blog/2024-02-28-maci-v1.2.0.md b/website/blog/2024-02-28-maci-v1.2.0.md
@@ -82,7 +82,7 @@ This platform will serve as the definitive resource for all information related
 
 Thanks to thorough reviews by PSE's internal Audit team, clr.fund's developer, [yuetloo](https://github.com/yuetloo), and our core development team, we've identified and addressed several bugs during our recent refactoring efforts. Most notably, a critical bug in MACI v1.x discovered by [Kyle](https://github.com/kcharbo3), which could have allowed coordinators to censor votes, has been [fixed](https://github.com/privacy-scaling-explorations/maci/pull/1170).
 
-For more details on our recent audit, please [refer to our audit docs](/docs/audit#pse-audit-2024) or [view the full report](/audit_reports/20240223_PSE_Audit_audit_report.pdf).
+For more details on our recent audit, please [refer to our audit docs](/docs/security/audit#pse-audit-2024) or [view the full report](/audit_reports/20240223_PSE_Audit_audit_report.pdf).
 
 After this audit and the resulting fixes, we feel more confident with MACI and its security.
 
@@ -92,7 +92,7 @@ Following the successful completion of our [MACI trusted setup ceremony](https:/
 
 To accomplish this, we'll leverage the tooling of [P0tion](https://github.com/privacy-scaling-explorations/p0tion), which helps to streamline and automate Groth16 phase2 ceremonies.
 
-We'll update this page after the ceremony completes to include the production-ready zkey artifacts. In the meantime, the artifacts for v.1.1.1 can be found on our [website](/docs/trusted-setup), and the [`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/tallyVotes.circom) artifacts can still be used in production.
+We'll update this page after the ceremony completes to include the production-ready zkey artifacts. In the meantime, the artifacts for v.1.1.1 can be found on our [website](/docs/security/trusted-setup), and the [`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/tallyVotes.circom) artifacts can still be used in production.
 
 ## Get Involved
 

diff --git a/website/blog/2024-04-10-roadmap-q2.md b/website/blog/2024-04-10-roadmap-q2.md
@@ -56,7 +56,7 @@ This quarter we're excited to keep building out MACI-RPGF with additional functi
 
 From [years of supporting QF rounds on MACI](https://qf.pse.dev/case-studies) we've learned a lot about the pain-points of community organizers. The blunt truth is that many technical barriers still exist - in order to operate a MACI poll (whether in a QF round or a simple voting application), you essentially must be a developer to deploy the smart contracts, execute on-chain transactions, and run tooling to generate zero-knowledge proofs to guarantee the integrity of a MACI poll. This is no trivial feat, and as a result, MACI is simply not a viable option for many communities to use today.
 
-We're aiming to change this by building a "Coordinator Service" to simplify the [role of the coordinator](/docs/workflow#coordinator), automate tasks, and remove technical barriers to running MACI-RPGF (and all MACI) rounds. This will include a web interface to deploy and operate MACI instances as well as a server to generate proofs and submit them on-chain. We're confident this tooling will accelerate community adoption by offloading the technical overhead and domain knowledge currently required to use this technology stack. More details to come on this soon!
+We're aiming to change this by building a "Coordinator Service" to simplify the [role of the coordinator](/docs/quick-start/workflow#coordinator), automate tasks, and remove technical barriers to running MACI-RPGF (and all MACI) rounds. This will include a web interface to deploy and operate MACI instances as well as a server to generate proofs and submit them on-chain. We're confident this tooling will accelerate community adoption by offloading the technical overhead and domain knowledge currently required to use this technology stack. More details to come on this soon!
 
 ### 🎯 MACI Core Protocol Improvements
 
@@ -66,7 +66,7 @@ Currently, we have a couple of focus areas:
 
 **Unconditional Privacy**
 
-As of now, MACI's [coordinator](/docs/workflow#coordinator) can track [user key changes](/docs/key-change), which allows them to associate voters with their respective votes, and thus potentially collude with bribers to deanonymize users. We're investigating ways to prevent this possibility. The [3227](https://3327.io/) team implemented a [proof of concept](https://github.com/privacy-scaling-explorations/maci/issues/796) using El-Gamal to remove the link between a new MACI key and their original key. Furthermore, there is a proposal under discussion on how to implement anonymous poll signups, which would provide the same benefits of the El-Gamal protocol, though with a much better user experience.
+As of now, MACI's [coordinator](/docs/quick-start/workflow#coordinator) can track [user key changes](/docs/core-concepts/key-change), which allows them to associate voters with their respective votes, and thus potentially collude with bribers to deanonymize users. We're investigating ways to prevent this possibility. The [3227](https://3327.io/) team implemented a [proof of concept](https://github.com/privacy-scaling-explorations/maci/issues/796) using El-Gamal to remove the link between a new MACI key and their original key. Furthermore, there is a proposal under discussion on how to implement anonymous poll signups, which would provide the same benefits of the El-Gamal protocol, though with a much better user experience.
 
 **Deployment Improvements**
 

diff --git a/website/blog/2024-05-08-ethdam.md b/website/blog/2024-05-08-ethdam.md
@@ -10,7 +10,7 @@ authors:
 tags: [security, bug, babyjubjub, input validation]
 ---
 
-During [ETHDam's Quadratic Funding round](https://ethdamqf.com/#/), run on [clr.fund](https://clr.fund), we discovered a critical bug in MACI. The issue stemmed from the lack of validation on MACI public keys within the [Poll contract](/docs/solidity-docs/Poll). A user (spoiler alert, it was a self-inflicted denial of service (DoS)) was able to submit a MACI public key which was not a point of the Baby JubJub elliptic curve, and it broke everything.
+During [ETHDam's Quadratic Funding round](https://ethdamqf.com/#/), run on [clr.fund](https://clr.fund), we discovered a critical bug in MACI. The issue stemmed from the lack of validation on MACI public keys within the [Poll contract](/docs/developers-references/smart-contracts/solidity-docs/Poll). A user (spoiler alert, it was a self-inflicted denial of service (DoS)) was able to submit a MACI public key which was not a point of the Baby JubJub elliptic curve, and it broke everything.
 
 ## So... what happened, really?
 

diff --git a/website/src/scripts/setupSolidityDocs.ts b/website/src/scripts/setupSolidityDocs.ts
@@ -4,7 +4,10 @@ import path from "path";
 import { copyDirectory, insertIndexPage } from "./utils";
 
 // where to move the solidity doc files over
-const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.3_alpha/solidity-docs");
+const solidityDocDir = path.resolve(
+  __dirname,
+  "../../versioned_docs/version-v2.0_alpha/developers-references/smart-contracts/solidity-docs",
+);
 // the origin folder (from the contracts package)
 const sourceDir = path.resolve(__dirname, "../../../contracts/docs");
 

diff --git a/website/src/scripts/setupTypedoc.ts b/website/src/scripts/setupTypedoc.ts
@@ -80,11 +80,14 @@ function defineTargetDirectory() {
     const versionContent = fs.readFileSync(versionFile, "utf8");
     if (versionContent) {
       const versionContentJson = JSON.parse(versionContent) as string[];
-      return path.resolve(__dirname, `../../versioned_docs/version-${versionContentJson[0]}/typedoc`);
+      return path.resolve(
+        __dirname,
+        `../../versioned_docs/version-${versionContentJson[0]}/developers-references/typescript-code/typedoc`,
+      );
     }
   }
 
-  return path.resolve(__dirname, "../../docs/typedoc");
+  return path.resolve(__dirname, "../../docs/developers-references/typescript-code/typedoc");
 }
 
 if (fs.existsSync(TYPEDOC_DIR)) {

diff --git a/website/versioned_docs/version-v1.2/circuits.md b/website/versioned_docs/version-v1.2/circuits.md
@@ -241,7 +241,7 @@ The hash is computed using the `sha256` Solidity function and is then subject to
 | 4th 50 bits | `numSignUps`      |
 | 5th 50 bits | `batchStartIndex` |
 
-`numSignUps`, a value provided by the contract, is the number of users who have signed up. This is one less than the number of leaves inserted in the state tree (since the 0th state leaf is a [blank state leaf](./primitives#state-leaf)). `batchStartIndex` is the ballot tree index at which the batch begins.
+`numSignUps`, a value provided by the contract, is the number of users who have signed up. This is one less than the number of leaves inserted in the state tree (since the 0th state leaf is a [blank state leaf](/docs/core-concepts/primitives#state-leaf)). `batchStartIndex` is the ballot tree index at which the batch begins.
 
 For instance, if `numSignUps` is 25 and the batch index is `5`, and all other values are 0, the following is the `packedVals` representation in hexadecimal:
 

diff --git a/website/versioned_docs/version-v1.2/spec.md b/website/versioned_docs/version-v1.2/spec.md
@@ -8,7 +8,7 @@ sidebar_position: 17
 # MACI v1.0 Specification
 
 :::info
-This document is a copy of the [MACI 1.0 Specification (for audit) document](https://hackmd.io/AP6zPSgtThWxx6pjXY7R8A), created in July 2021 for one of [MACI's formal audits](/docs/audit).
+This document is a copy of the [MACI 1.0 Specification (for audit) document](https://hackmd.io/AP6zPSgtThWxx6pjXY7R8A), created in July 2021 for one of [MACI's formal audits](/docs/security/audit).
 
 This historical document is stored here for informational purposes. We do not intend to edit it. As a result, some of the information within this document may be outdated.
 :::

diff --git a/website/versioned_docs/version-v1.2/typedoc/cli/modules.md b/website/versioned_docs/version-v1.2/typedoc/cli/modules.md
@@ -98,7 +98,7 @@ Whether the verifying keys match or not
 
 **`Note`**
 
-see different options for zkey files to use specific circuits https://maci.pse.dev/docs/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
+see different options for zkey files to use specific circuits https://maci.pse.dev/docs/security/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
 
 #### Defined in
 
@@ -295,7 +295,7 @@ The tally data
 
 **`Note`**
 
-see different options for zkey files to use specific circuits https://maci.pse.dev/docs/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
+see different options for zkey files to use specific circuits https://maci.pse.dev/docs/security/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
 
 #### Defined in
 
@@ -459,7 +459,7 @@ Function that sets the verifying keys in the VkRegistry contract
 
 **`Note`**
 
-see different options for zkey files to use specific circuits https://maci.pse.dev/docs/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
+see different options for zkey files to use specific circuits https://maci.pse.dev/docs/security/trusted-setup, https://maci.pse.dev/docs/testing/#pre-compiled-artifacts-for-testing
 
 #### Defined in
 

diff --git a/website/versioned_docs/version-v1.3_alpha/topup.md b/website/versioned_docs/version-v1.3_alpha/topup.md
diff --git a/website/versioned_docs/version-v2.0_alpha/contributing/_category_.json b/website/versioned_docs/version-v2.0_alpha/contributing/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Contributing",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "description": "MACI's contribution guidelines."
+  }
+}
diff --git a/...1.3_alpha/contributing/code-of-conduct.md → ...2.0_alpha/contributing/code-of-conduct.md b/...1.3_alpha/contributing/code-of-conduct.md → ...2.0_alpha/contributing/code-of-conduct.md
@@ -2,6 +2,7 @@
 title: MACI Contributor Code of Conduct
 description: The Contributor Covenant Code of Conduct for MACI
 sidebar_label: Code of Conduct
+sidebar_position: 2
 ---
 
 # Contributor Covenant Code of Conduct

diff --git a/...n-v1.3_alpha/contributing/contributing.md → ...n-v2.0_alpha/contributing/contributing.md b/...n-v1.3_alpha/contributing/contributing.md → ...n-v2.0_alpha/contributing/contributing.md
@@ -2,7 +2,7 @@
 title: Contributing to MACI
 description: Instructions on how to contribute to MACI
 sidebar_label: Contributing
-sidebar_position: 21
+sidebar_position: 1
 ---
 
 # Contributing

diff --git a/website/versioned_docs/version-v2.0_alpha/core-concepts/_category_.json b/website/versioned_docs/version-v2.0_alpha/core-concepts/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Core Concepts",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Understand MACI's core concepts."
+  }
+}
diff --git a/...sion-v1.3_alpha/coordinator-processing.md → ...a/core-concepts/coordinator-processing.md b/...sion-v1.3_alpha/coordinator-processing.md → ...a/core-concepts/coordinator-processing.md
@@ -2,7 +2,7 @@
 title: Coordinator local processing
 description: How does the coordinator process and tally messages locally
 sidebar_label: Coordinator local processing
-sidebar_position: 16
+sidebar_position: 3
 ---
 
 # Coordinator local processing

diff --git a/...ned_docs/version-v1.3_alpha/key-change.md → ...on-v2.0_alpha/core-concepts/key-change.md b/...ned_docs/version-v1.3_alpha/key-change.md → ...on-v2.0_alpha/core-concepts/key-change.md
@@ -2,7 +2,7 @@
 title: MACI key change
 description: How key change messages work
 sidebar_label: Key change
-sidebar_position: 18
+sidebar_position: 4
 ---
 
 # MACI Key Change

diff --git a/...ned_docs/version-v1.3_alpha/poll-types.md → ...on-v2.0_alpha/core-concepts/poll-types.md b/...ned_docs/version-v1.3_alpha/poll-types.md → ...on-v2.0_alpha/core-concepts/poll-types.md
diff --git a/...ned_docs/version-v1.3_alpha/primitives.md → ...on-v2.0_alpha/core-concepts/primitives.md b/...ned_docs/version-v1.3_alpha/primitives.md → ...on-v2.0_alpha/core-concepts/primitives.md
@@ -2,7 +2,7 @@
 title: MACI Primitives
 description: A short introduction of the main primitives used by MACI
 sidebar_label: Primitives
-sidebar_position: 6
+sidebar_position: 1
 ---
 
 ## MACI primitives

diff --git a/...versioned_docs/version-v1.3_alpha/spec.md → .../version-v2.0_alpha/core-concepts/spec.md b/...versioned_docs/version-v1.3_alpha/spec.md → .../version-v2.0_alpha/core-concepts/spec.md
@@ -2,13 +2,13 @@
 title: MACI v1.0 Specification
 description: A detailed specification meant to assist auditors in reviewing MACI version 1.0
 sidebar_label: Specification
-sidebar_position: 17
+sidebar_position: 5
 ---
 
 # MACI v1.0 Specification
 
 :::info
-This document is a copy of the [MACI 1.0 Specification (for audit) document](https://hackmd.io/AP6zPSgtThWxx6pjXY7R8A), created in July 2021 for one of [MACI's formal audits](/docs/audit).
+This document is a copy of the [MACI 1.0 Specification (for audit) document](https://hackmd.io/AP6zPSgtThWxx6pjXY7R8A), created in July 2021 for one of [MACI's formal audits](/docs/security/audit).
 
 This historical document is stored here for informational purposes. We do not intend to edit it. As a result, some of the information within this document may be outdated.
 :::

diff --git a/website/versioned_docs/version-v2.0_alpha/developers-references/_category_.json b/website/versioned_docs/version-v2.0_alpha/developers-references/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Developers References",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Documentation for developers looking to understand all MACI's components."
+  }
+}
diff --git a/...ed_docs/version-v1.3_alpha/integrating.md → ...lpha/developers-references/integrating.md b/...ed_docs/version-v1.3_alpha/integrating.md → ...lpha/developers-references/integrating.md
@@ -2,7 +2,7 @@
 title: Integrating MACI
 description: How to integrate MACI into your application
 sidebar_label: Integrating
-sidebar_position: 13
+sidebar_position: 1
 ---
 
 # Integrating MACI
@@ -17,7 +17,7 @@ First, you need to deploy contracts to start using MACI. This could be done thro
 
 ### Via `maci-cli`
 
-This can be easily done via [`maci-cli`](/docs/cli#subcommands).
+This can be easily done via [`maci-cli`](/docs/developers-references/typescript-code/cli#subcommands).
 Deployment order is:
 
 1. Deploy crypto (Hasher, Poseidon)
@@ -31,7 +31,7 @@ Deployment order is:
 9. Deploy MACI, AccQueueQuinaryMaci
 10. Deploy Poll, AccQueueQuinaryMaci, MessageProcessor, Tally and Subsidy (optional)
 
-Before running the deploy command make sure you have [zkey files](https://maci.pse.dev/docs/trusted-setup) from trusted setup and env variables `ETH_PROVIDER` (RPC endpoint) and `ETH_SK` (wallet private key) are set. For production environment make sure you don't use zkey files from our examples.
+Before running the deploy command make sure you have [zkey files](https://maci.pse.dev/docs/security/trusted-setup) from trusted setup and env variables `ETH_PROVIDER` (RPC endpoint) and `ETH_SK` (wallet private key) are set. For production environment make sure you don't use zkey files from our examples.
 
 :::note Non Quadratic Voting
 
@@ -194,7 +194,7 @@ The network options are: **_localhost, sepolia, and optimism-sepolia_**, and the
 
 ## MACI Contract
 
-The MACI contract is the core of the protocol. Contracts can inherit from MACI and thus expose the signup and topup functions. As with standalone MACI, one would need to deploy a [sign up gatekeeper](./contracts#signupgatekeeper) as well as the [voice credit proxy](./contracts#voicecreditproxy).
+The MACI contract is the core of the protocol. Contracts can inherit from MACI and thus expose the signup and topup functions. As with standalone MACI, one would need to deploy a [sign up gatekeeper](/docs/developers-references/smart-contracts/contracts#signupgatekeeper) as well as the [voice credit proxy](/docs/developers-references/smart-contracts/contracts#voicecreditproxy).
 
 As an example, within the quadratic funding infrastructure project, the QFI contract inherits from MACI and allows sign up via the contribute function.