Skip to content

Commit

Permalink
docs: update generated docs to include version in module names (#296)
Browse files Browse the repository at this point in the history
Updates to latest aegir version with simplified readmes, auto-copying
@packageDocumentation to "About" section and includes version numbers
in the module versions.
  • Loading branch information
achingbrain authored Nov 2, 2023
1 parent dbbee17 commit 0776106
Show file tree
Hide file tree
Showing 12 changed files with 72 additions and 92 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: ci
name: CI
on:
push:
branches:
Expand Down
12 changes: 12 additions & 0 deletions .github/workflows/semantic-pull-request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
name: Semantic PR

on:
pull_request_target:
types:
- opened
- edited
- synchronize

jobs:
main:
uses: pl-strflt/.github/.github/workflows/[email protected]
68 changes: 23 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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)
Expand All @@ -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).

Expand All @@ -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

Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
25 changes: 17 additions & 8 deletions packages/helia/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
14 changes: 6 additions & 8 deletions packages/helia/src/index.ts
Original file line number Diff line number Diff line change
@@ -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'))
* ```
*/
Expand Down
6 changes: 4 additions & 2 deletions packages/helia/typedoc.json
Original file line number Diff line number Diff line change
@@ -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
}
9 changes: 0 additions & 9 deletions packages/interface/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/interface/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @packageDocumentation
*
* The API defined by a Helia node
* The API defined by a {@link Helia} node
*
* @example
*
Expand Down
3 changes: 2 additions & 1 deletion packages/interface/typedoc.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,6 @@
"./src/index.ts",
"./src/blocks.ts",
"./src/pins.ts"
]
],
"includeVersion": true
}
14 changes: 0 additions & 14 deletions packages/interop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
5 changes: 4 additions & 1 deletion typedoc.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
{
"$schema": "https://typedoc.org/schema.json",
"name": "Helia"
"name": "Helia",
"exclude": [
"packages/interop"
]
}

0 comments on commit 0776106

Please sign in to comment.