From 1f48b1bf6d40691042e3ef303f119a407e73d148 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Mon, 30 Oct 2023 13:40:14 +0000 Subject: [PATCH] docs: update generated docs to include version in module names Updates to latest aegir version with simplified readmes, auto-copying @packageDocumentation to "About" section and includes version numbers in the module versions. --- .github/workflows/main.yml | 2 +- .github/workflows/semantic-pull-request.yml | 12 ++++ README.md | 68 +++++++-------------- package.json | 4 +- packages/helia/README.md | 25 +++++--- packages/helia/src/index.ts | 14 ++--- packages/helia/typedoc.json | 6 +- packages/interface/README.md | 9 --- packages/interface/src/index.ts | 2 +- packages/interface/typedoc.json | 3 +- packages/interop/README.md | 14 ----- typedoc.json | 5 +- 12 files changed, 72 insertions(+), 92 deletions(-) create mode 100644 .github/workflows/semantic-pull-request.yml diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 796988f84..e3c84b2ad 100644 --- 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 new file mode 100644 index 000000000..bd00f090c --- /dev/null +++ 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 index c07f1d576..30306e2e8 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@

-# helia - [![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 - -- [🌟 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 index bda639add..bf11c3223 100644 --- 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 index b277a178c..39305c142 100644 --- a/packages/helia/README.md +++ b/packages/helia/README.md @@ -4,8 +4,6 @@

-# helia - [![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) @@ -13,13 +11,24 @@ > An implementation of IPFS in JavaScript -## Table of contents +## 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 ` ``` -## API Docs - -- - ## License Licensed under either of diff --git a/typedoc.json b/typedoc.json index b5cbc6721..ffab8cecf 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,4 +1,7 @@ { "$schema": "https://typedoc.org/schema.json", - "name": "Helia" + "name": "Helia", + "exclude": [ + "packages/interop" + ] }