Fix/broken anchors docs (#328)

* ci: brokenAnchors for linked typed list fixed * ci: Add and moddify helpers, functions and handlebars * ci: manual fixes in .md and .ts files * Apply suggestions from code review Co-authored-by: Rekard0 <[email protected]> * ci: requested changes from code review * Feature: Add support for osx-configs (#324) * add support for osx-configs * update for new configs * fix comments and update yarn lock * fix comments * fix tests * fix sonar * fix sonar * refactor getNetwork function * fix comments * fix: throw error when repo contract is not available * fix: build --------- Co-authored-by: Rekard0 <[email protected]> Co-authored-by: josemarinas <[email protected]>
aragon · Mar 1, 2024 · e132db3 · e132db3
1 parent e53f221
commit e132db3
Show file tree

Hide file tree

Showing 11 changed files with 120 additions and 19 deletions.
diff --git a/docs/sdk/03-update-security-check/index.md b/docs/sdk/03-update-security-check/index.md
@@ -168,13 +168,12 @@ The `applyUpdate` action CAN be wrapped by `grant` and `revoke` actions:
 |                | `"invalidGrantRootPermissionPermissionName"`  | The `permissionName` must be `ROOT_PERMISSION`.                                                                                                      |
 |                | `"invalidRevokeRootPermissionPermissionName"` | "                                                                                                                                                    |
 
-[execute]: (../../../../osx/how-it-works/core/dao/actions#a-deep-dive-into-actions-and-execution)
-[action]: (../../../../osx/how-it-works/core/dao/actions#actions)
-[allowfailuremap]: (../../../../osx/how-it-works/core/dao/actions#allowing-for-failure)
-[initializefrom]: (../../../../osx/reference-guide/core/dao#external-function-initializefrom)
+[execute]: ../../osx/01-how-it-works/01-core/01-dao/01-actions.md#a-deep-dive-into-actions-and-execution
+[action]: ../../osx/01-how-it-works/01-core/01-dao/01-actions.md#actions
+[allowfailuremap]: ../../osx/01-how-it-works/01-core/01-dao/01-actions.md#allowing-for-failure
+[initializefrom]: ../../osx/03-reference-guide/core/dao/DAO.md#external-function-initializefrom
 [oz-upgradeto]: https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/3d4c0d5741b131c231e558d7a6213392ab3672a5/contracts/proxy/utils/UUPSUpgradeable.sol#L74-L77
 [oz-upgradetoandcall]: https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/3d4c0d5741b131c231e558d7a6213392ab3672a5/contracts/proxy/utils/UUPSUpgradeable.sol#L89-L92
-[applyupdate]: (../../../../osx/reference-guide/framework/plugin/setup/PluginSetupProcessor#external-function-applyupdate)
-[grant]: (../../../../osx/reference-guide/core/permission/PermissionManager#external-function-grant)
-[revoke]: (../../../../osx/reference-guide/core/permission/PermissionManager#external-function-revoke)
-[build-metadata]: (../../../../osx/how-to-guides/plugin-development/publication/metadata#plugin-metadata-specification)
+[applyupdate]: ../../osx/03-reference-guide/framework/plugin/setup/PluginSetupProcessor.md#external-function-applyupdate
+[grant]: ../../osx/03-reference-guide/core/permission/PermissionManager.md#external-function-grant
+[revoke]: ../../osx/03-reference-guide/core/permission/PermissionManager.md#external-function-revoke
diff --git a/docs/tweaks/custom-link.hbs b/docs/tweaks/custom-link.hbs
@@ -0,0 +1,25 @@
+{{! usage: link to="namepath" html=true/false caption="optional caption"~}}
+
+{{~#if html~}}
+<code>
+
+{{~#link to~}}
+{{#if url~}}
+<a href="{{{url}}}">{{#if ../../caption}}{{../../../caption}}{{else}}{{name}}{{/if}}</a>
+{{~else~}}
+{{#if ../../caption}}{{../../../caption}}{{else}}{{name}}{{/if~}}
+{{/if~}}
+{{/link~}}
+
+</code>
+{{~else~}}
+
+{{#link to~}}
+{{#if url~}}
+[<code>{{#if ../../caption}}{{escape ../../../caption}}{{else}}{{escape name}}{{/if}}</code>]({{{toLowerCase url}}})
+{{~else~}}
+{{#if ../../caption}}{{escape ../../../caption}}{{else}}{{{escape (toLowerCase (extractText name))}}}{{/if~}}
+{{~/if~}}
+{{/link~}}
+
+{{/if~}}
diff --git a/docs/tweaks/custom-linked-type-list.hbs b/docs/tweaks/custom-linked-type-list.hbs
@@ -0,0 +1,4 @@
+{{#each types~}}
+{{>custom-link to=this html=../html ~}}
+{{#unless @last}}{{{../delimiter}}}{{/unless~}}
+{{/each}}
diff --git a/docs/tweaks/ddata.js b/docs/tweaks/ddata.js
@@ -0,0 +1,41 @@
+const util = require("util");
+
+exports.anchorName = anchorName;
+
+function anchorName(options) {
+  const methodSign = options.data.methodSign
+    ? options.data.methodSign
+        .replace(/[^\w\s]/g, "")
+        .replace(/\s+/g, "-")
+        .toLowerCase()
+    : "";
+
+  if (!this.id)
+    throw new Error(
+      "[anchorName helper] cannot create a link without a id: " +
+        JSON.stringify(this)
+    );
+  if (this.inherited) {
+    options.hash.id = this.inherits;
+    const inherits = _identifier(options);
+    if (inherits) {
+      return anchorName.call(inherits, options);
+    } else {
+      return "";
+    }
+  }
+
+  return util.format(
+    "%s%s%s%s",
+    this.isExported ? "exp_" : "",
+    this.kind === "constructor" ? "new_" : "",
+    this.id
+      .replace(/:/g, "_")
+      .replace(/~/g, "..")
+      .replace(/\(\)/g, "_new")
+      .replace(/#/g, "")
+      .replace(/\./g, "")
+      .toLowerCase(),
+    methodSign
+  );
+}
diff --git a/docs/tweaks/helpers.js b/docs/tweaks/helpers.js
@@ -1,11 +1,19 @@
-
-exports.stripTags = stripTags
+exports.toLowerCase = toLowerCase;
+exports.stripTags = stripTags;
+exports.extractText = extractText;
 
 function stripTags(input) {
-    // Replace HTML entities with their corresponding characters
-    var decodedInput = input.replace(/&lt;/g, '<').replace(/&gt;/g, '>');
-    // Remove <p> tags
-    return decodedInput.replace(/<\/?p>/ig, "");
+  // Replace HTML entities with their corresponding characters
+  const decodedInput = input.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  // Remove <p> tags
+  return decodedInput.replace(/<\/?p>/gi, "");
+}
+
+function toLowerCase(input) {
+  return input.toLowerCase();
 }
 
-
+function extractText(input) {
+  // Keep only alphabetic characters (a-z, A-Z)
+  return input.match(/[a-zA-Z0-9]+/g).join("");
+}
diff --git a/docs/tweaks/scope.hbs b/docs/tweaks/scope.hbs
@@ -0,0 +1,10 @@
+{{#if scope}}
+**Kind**: {{#if (equal kind "event") ~}}
+event emitted{{#if memberof}} by {{>link to=memberof}}{{/if}}  
+{{else~}}
+{{scope}} {{#if virtual}}abstract {{/if}}{{kindInThisContext}}{{#if memberof}} of {{>custom-link to=memberof}}{{/if}}  
+{{/if~}}
+{{else~}}
+{{#if isExported}}**Kind**: Exported {{kind}}  
+{{/if~}}
+{{/if~}}
diff --git a/docs/tweaks/sig-link.hbs b/docs/tweaks/sig-link.hbs
@@ -0,0 +1,14 @@
+{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}}
+{{#if name}}{{#sig~}}
+{{{@depOpen}~}}
+[{{{@codeOpen}~}}
+{{#if @prefix}}{{@prefix}} {{/if~}}
+{{@accessSymbol}}{{#if (isEvent)}}"{{{name}}}"{{else}}{{{name}}}{{/if~}}
+{{~#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}}
+{{{@codeClose}}}](#{{{anchorName}}}{{#if @returnTypes}}--{{>custom-linked-type-list types=@returnTypes delimiter="--" }}{{/if~}})
+{{~#if @returnSymbol}} {{@returnSymbol}}{{/if~}}
+{{#if @returnTypes}} {{>linked-type-list types=@returnTypes delimiter=" \| " }}{{/if~}}
+{{#if @suffix}} {{@suffix}}{{/if~}}
+{{{@depClose}~}}
+{{~/sig}}{{/if~}}
+{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}}
diff --git a/modules/client/src/addresslistVoting/internal/client/methods.ts b/modules/client/src/addresslistVoting/internal/client/methods.ts
@@ -589,7 +589,7 @@ export class AddresslistVotingClientMethods extends ClientCore
    * @param params.pluginAddress - The address of the plugin.
    * @param params.address - The address to check.
    * @param params.blockNumber - The block number for specifying a specific block.
-   * @returns A boolean indicating whether the address is a member or not.
+   * @returns {boolean} A boolean indicating whether the address is a member or not.
    */
   public async isMember(params: IsMemberParams): Promise<boolean> {
     IsMemberSchema.strict().validateSync(params);

diff --git a/modules/client/src/multisig/internal/client/methods.ts b/modules/client/src/multisig/internal/client/methods.ts
@@ -576,7 +576,7 @@ export class MultisigClientMethods extends ClientCore
    * @param params.pluginAddress - The address of the plugin.
    * @param params.address - The address to check.
    * @param params.blockNumber - The block number for specifying a specific block.
-   * @returns A boolean indicating whether the address is a member or not.
+   * @returns {boolean} A boolean indicating whether the address is a member or not.
    */
   public async isMember(params: IsMemberParams): Promise<boolean> {
     IsMemberSchema.strict().validateSync(params);

diff --git a/modules/client/src/tokenVoting/internal/client/methods.ts b/modules/client/src/tokenVoting/internal/client/methods.ts
@@ -843,7 +843,7 @@ export class TokenVotingClientMethods extends ClientCore
    * @param params.pluginAddress - The address of the plugin.
    * @param params.address - The address to check.
    * @param params.blockNumber - The block number for specifying a specific block.
-   * @returns A boolean indicating whether the address is a member or not.
+   * @returns {boolean} A boolean indicating whether the address is a member or not.
    */
   public async isMember(params: IsMemberParams): Promise<boolean> {
     IsMemberSchema.strict().validateSync(params);

diff --git a/package.json b/package.json
@@ -28,8 +28,8 @@
     "docs:examples": "node ./modules/client/scripts/generate-markdown.js ./modules/client/examples && rsync -avr --prune-empty-dirs --remove-source-files --include='*/' --include='*.md' --exclude='*' ./modules/client/examples/ ./docs/sdk/01-examples/ --delete;"
   },
   "devDependencies": {
-    "@babel/preset-typescript": "^7.18.6",
     "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
+    "@babel/preset-typescript": "^7.18.6",
     "jsdoc-babel": "^0.5.0",
     "jsdoc-to-markdown": "^8.0.1",
     "turbo": "^1.1.9"