docs: update generated docs to include version in module names (#296)

Updates to latest aegir version with simplified readmes, auto-copying @packageDocumentation to "About" section and includes version numbers in the module versions.
ipfs · Nov 2, 2023 · 0776106 · 0776106
1 parent dbbee17
commit 0776106
Show file tree

Hide file tree

Showing 12 changed files with 72 additions and 92 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,4 +1,4 @@
-name: ci
+name: CI
 on:
   push:
     branches:

diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.yml
@@ -0,0 +1,12 @@
+name: Semantic PR
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    uses: pl-strflt/.github/.github/workflows/reusable-semantic-pull-request.yml@v0.3
diff --git a/README.md b/README.md
@@ -4,8 +4,6 @@
   </a>
 </p>
 
-# helia <!-- omit in toc -->
-
 [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
 [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
 [![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
@@ -15,12 +13,12 @@
 
 See the [Manifesto](https://github.com/ipfs/helia/wiki/Manifesto), the [FAQ](https://github.com/ipfs/helia/wiki/FAQ), and the [State of IPFS in JS blog post from October 2022](https://blog.ipfs.tech/state-of-ipfs-in-js/) for more info.
 
-## 🌟 Usage
+# 🌟 Usage
 
 A quick overview of how to get different types of data in and out of your Helia
 node.
 
-### 🪢 Strings
+## 🪢 Strings
 
 You can use the [@helia/strings](https://www.npmjs.com/package/@helia/strings)
 module to easily add and get strings from your Helia node:
@@ -38,7 +36,7 @@ console.log(await s.get(myImmutableAddress))
 // hello world
 ```
 
-### 🌃 JSON
+## 🌃 JSON
 
 The [@helia/json](https://www.npmjs.com/package/@helia/json) module lets you add
 or get plain JS objects:
@@ -56,7 +54,7 @@ console.log(await j.get(myImmutableAddress))
 // { hello: 'world' }
 ```
 
-### 🌠 DAG-JSON
+## 🌠 DAG-JSON
 
 The [@helia/dag-json](https://www.npmjs.com/package/@helia/dag-json) allows you
 to store references to linked objects as
@@ -83,7 +81,7 @@ console.log(await d.get(retrievedObject.link))
 // { hello: 'world' }
 ```
 
-### 🌌 DAG-CBOR
+## 🌌 DAG-CBOR
 
 [@helia/dag-cbor](https://www.npmjs.com/package/@helia/dag-cbor) works in a
 similar way to `@helia/dag-json` but stores objects using
@@ -110,45 +108,24 @@ console.log(await d.get(retrievedObject.link))
 // { hello: 'world' }
 ```
 
-### 🐾 Next steps
+# 🐾 Next steps
 
 Check out the [helia-examples](https://github.com/ipfs-examples/helia-examples)
 repo for how to do mostly anything with your Helia node.
 
-## Table of contents <!-- omit in toc -->
-
-- [🌟 Usage](#-usage)
-  - [🪢 Strings](#-strings)
-  - [🌃 JSON](#-json)
-  - [🌠 DAG-JSON](#-dag-json)
-  - [🌌 DAG-CBOR](#-dag-cbor)
-  - [🐾 Next steps](#-next-steps)
-- [🏃‍♀️ Getting Started](#️-getting-started)
-- [📗 Project Docs](#-project-docs)
-- [📒 API Docs](#-api-docs)
-- [📐 System diagram](#-system-diagram)
-- [🏭 Code Structure](#-code-structure)
-- [📣 Project status](#-project-status)
-- [🛣️ Roadmap](#️-roadmap)
-- [👫 Get involved](#-get-involved)
-  - [🤲 Contribute](#-contribute)
-- [🛍️ Notable Consumers/Users](#️-notable-consumersusers)
-- [🌞 Branding](#-branding)
-- [🪪 License](#-license)
-
-## 🏃‍♀️ Getting Started
+# 🏃‍♀️ Getting Started
 
 Check out the [Helia examples repo](https://github.com/ipfs-examples/helia-examples#examples), which covers a wide variety of use cases. If you feel something has been missed, follow the [contribution guide](https://github.com/ipfs-examples/helia-examples#contributing) and create a PR to the examples repo.
 
-## 📗 Project Docs
+# 📗 Project Docs
 
 - See the [project wiki](https://github.com/ipfs/helia/wiki).
 
-## 📒 API Docs
+# 📒 API Docs
 
 - https://ipfs.github.io/helia
 
-## 📐 System diagram
+# 📐 System diagram
 
 ```mermaid
 graph TD;
@@ -176,7 +153,7 @@ graph TD;
     Reframe-->Network;
 ```
 
-## 🏭 Code Structure
+# 🏭 Code Structure
 Helia embraces a modular approach and encourages users to bring their own implementations of interfacing libraries to suit their needs. Helia also ships supplemental libraries and tools including:
 
 - [`@helia/UnixFS`](https://github.com/ipfs/helia-unixfs)
@@ -195,19 +172,20 @@ This repo itself is made up of these packages:
 - [`/packages/helia`](./packages/helia) An implementation of the Helia API
 - [`/packages/interop`](./packages/interop) Interop tests for Helia
 
-## 📣 Project status
+# 📣 Project status
 Helia v1 shipped in 202303 (see [releases](https://github.com/ipfs/helia/releases)), and development keeps on trucking as we work on initiatives in the [roadmap](#roadmap) and make performance improvements and bug fixes along the way.
 
-## 🛣️ Roadmap
+# 🛣️ Roadmap
 Please find and comment on [the Roadmap here](https://github.com/ipfs/helia/issues/5).
 
-## 👫 Get involved
-* Watch our Helia Demo Day presentations [here](https://www.youtube.com/playlist?list=PLuhRWgmPaHtQAnt8INOe5-kV9TLVaUJ9v)
-* We are sharing about the progress at periodic [Helia Demos](https://lu.ma/helia).  This is a good place to find out the latest and learn of ways to get involved.  We'd love to see you there!
-* Pick up one of the [issues](https://github.com/ipfs/helia/issues).
-* Come chat in Filecoin Slack #ip-js.  (Yes, we should bridge this to other chat enviornments.  Please comment [here](https://github.com/ipfs/helia/issues/33) if you'd like this.)
+# 👫 Get involved
+
+- Watch our Helia Demo Day presentations [here](https://www.youtube.com/playlist?list=PLuhRWgmPaHtQAnt8INOe5-kV9TLVaUJ9v)
+- We are sharing about the progress at periodic [Helia Demos](https://lu.ma/helia).  This is a good place to find out the latest and learn of ways to get involved.  We'd love to see you there!
+- Pick up one of the [issues](https://github.com/ipfs/helia/issues).
+- Come chat in Filecoin Slack #ip-js.  (Yes, we should bridge this to other chat enviornments.  Please comment [here](https://github.com/ipfs/helia/issues/33) if you'd like this.)
 
-### 🤲 Contribute
+# 🤲 Contribute
 
 Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia/issues).
 
@@ -219,15 +197,15 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 
 [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
 
-## 🛍️ Notable Consumers/Users
+# 🛍️ Notable Consumers/Users
 
 - See [Projects using Helia](https://github.com/ipfs/helia/wiki/Projects-using-Helia).
 
-## 🌞 Branding
+# 🌞 Branding
 
 - See [Branding](https://github.com/ipfs/helia/wiki/Branding).
 
-## 🪪 License
+# 🪪 License
 
 Licensed under either of
 

diff --git a/package.json b/package.json
@@ -33,8 +33,8 @@
     "release": "run-s build docs:no-publish npm:release docs",
     "npm:release": "aegir exec --bail false npm -- publish",
     "release:rc": "aegir release-rc",
-    "docs": "NODE_OPTIONS=--max_old_space_size=8192 aegir docs -- --exclude packages/interop --excludeExternals",
-    "docs:no-publish": "NODE_OPTIONS=--max_old_space_size=8192 aegir docs --publish false -- --exclude packages/interop"
+    "docs": "aegir docs",
+    "docs:no-publish": "aegir docs --publish false"
   },
   "devDependencies": {
     "aegir": "^41.0.0",

diff --git a/packages/helia/README.md b/packages/helia/README.md
@@ -4,22 +4,31 @@
   </a>
 </p>
 
-# helia <!-- omit in toc -->
-
 [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
 [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
 [![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/main.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/main.yml?query=branch%3Amain)
 
 > An implementation of IPFS in JavaScript
 
-## Table of contents <!-- omit in toc -->
+## About
+
+Exports a `createHelia` function that returns an object that implements the Helia API.
+
+Pass it to other modules like @helia/unixfs to make files available on the distributed web.
+
+### Example
 
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
+```typescript
+import { createHelia } from 'helia'
+import { unixfs } from '@helia/unixfs'
+import { CID } from 'multiformats/cid'
+
+const helia = await createHelia()
+
+const fs = unixfs(helia)
+fs.cat(CID.parse('bafyFoo'))
+```
 
 ## Install
 

diff --git a/packages/helia/src/index.ts b/packages/helia/src/index.ts
@@ -1,22 +1,20 @@
 /**
  * @packageDocumentation
  *
- * Create a Helia node.
+ * Exports a `createHelia` function that returns an object that implements the {@link Helia} API.
+ *
+ * Pass it to other modules like {@link https://www.npmjs.com/package/@helia/unixfs | @helia/unixfs} to make files available on the distributed web.
  *
  * @example
  *
  * ```typescript
- * import { MemoryDatastore } from 'datastore-core'
- * import { MemoryBlockstore } from 'blockstore-core'
  * import { createHelia } from 'helia'
  * import { unixfs } from '@helia/unixfs'
  * import { CID } from 'multiformats/cid'
  *
- * const node = await createHelia({
- *   blockstore: new MemoryBlockstore(),
- *   datastore: new MemoryDatastore()
- * })
- * const fs = unixfs(node)
+ * const helia = await createHelia()
+ *
+ * const fs = unixfs(helia)
  * fs.cat(CID.parse('bafyFoo'))
  * ```
  */

diff --git a/packages/helia/typedoc.json b/packages/helia/typedoc.json
@@ -1,6 +1,8 @@
 {
   "entryPoints": [
     "./src/index.ts",
-    "./src/block-providers/index.ts"
-  ]
+    "./src/block-brokers/index.ts",
+    "./src/utils/default-hashers.ts"
+  ],
+  "includeVersion": true
 }
diff --git a/packages/interface/README.md b/packages/interface/README.md
@@ -4,22 +4,13 @@
   </a>
 </p>
 
-# @helia/interface <!-- omit in toc -->
-
 [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
 [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
 [![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/main.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/main.yml?query=branch%3Amain)
 
 > The Helia API
 
-## Table of contents <!-- omit in toc -->
-
-- [Install](#install)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
-
 ## Install
 
 ```console

diff --git a/packages/interface/src/index.ts b/packages/interface/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @packageDocumentation
  *
- * The API defined by a Helia node
+ * The API defined by a {@link Helia} node
  *
  * @example
  *

diff --git a/packages/interface/typedoc.json b/packages/interface/typedoc.json
@@ -3,5 +3,6 @@
     "./src/index.ts",
     "./src/blocks.ts",
     "./src/pins.ts"
-  ]
+  ],
+  "includeVersion": true
 }
diff --git a/packages/interop/README.md b/packages/interop/README.md
@@ -4,23 +4,13 @@
   </a>
 </p>
 
-# @helia/interop <!-- omit in toc -->
-
 [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
 [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
 [![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/main.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/main.yml?query=branch%3Amain)
 
 > Interop tests for Helia
 
-## Table of contents <!-- omit in toc -->
-
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
-
 ## Install
 
 ```console
@@ -35,10 +25,6 @@ Loading this module through a script tag will make it's exports available as `He
 <script src="https://unpkg.com/@helia/interop/dist/index.min.js"></script>
 ```
 
-## API Docs
-
-- <https://ipfs.github.io/helia/modules/_helia_interop.html>
-
 ## License
 
 Licensed under either of

diff --git a/typedoc.json b/typedoc.json
@@ -1,4 +1,7 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "name": "Helia"
+  "name": "Helia",
+  "exclude": [
+    "packages/interop"
+  ]
 }