docs: update project config and readmes (#47)

Updates config to build all docs and simplify readmes.
ipfs · Oct 30, 2023 · 31eb6f7 · 31eb6f7
1 parent b130c17
commit 31eb6f7
Show file tree

Hide file tree

Showing 13 changed files with 135 additions and 71 deletions.
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/[email protected]
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -2,25 +2,12 @@ name: Close and mark stale issue
 
 on:
   schedule:
-  - cron: '0 0 * * *'
+    - cron: '0 0 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
 
 jobs:
   stale:
-
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-
-    steps:
-    - uses: actions/stale@v3
-      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        stale-issue-message: 'Oops, seems like we needed more information for this issue, please comment with more details or this issue will be closed in 7 days.'
-        close-issue-message: 'This issue was closed because it is missing author input.'
-        stale-issue-label: 'kind/stale'
-        any-of-labels: 'need/author-input'
-        exempt-issue-labels: 'need/triage,need/community-input,need/maintainer-input,need/maintainers-input,need/analysis,status/blocked,status/in-progress,status/ready,status/deferred,status/inactive'
-        days-before-issue-stale: 6
-        days-before-issue-close: 7
-        enable-statistics: true
+    uses: pl-strflt/.github/.github/workflows/[email protected]
diff --git a/README.md b/README.md
@@ -4,25 +4,18 @@
   </a>
 </p>
 
-# helia-delegated-routing-v1-http-api <!-- 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-delegated-routing-v1-http-api.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia-delegated-routing-v1-http-api)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia-delegated-routing-v1-http-api/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia-delegated-routing-v1-http-api/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > The Delegated Routing V1 HTTP API powered by Helia
 
-This repo contains a server implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) along with a client that can be used to interact with any compliant server implementation.
-
-## Table of contents <!-- omit in toc -->
+## About
 
-- [Structure](#structure)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
+This repo contains a server implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) along with a client that can be used to interact with any compliant server implementation.
 
-## Structure
+## Packages
 
 - [`/packages/client`](./packages/client) A Delegated Routing V1 HTTP API client
 - [`/packages/interop`](./packages/interop) Interop tests for the Delegated Routing V1 HTTP API server powered by Helia

diff --git a/package.json b/package.json
@@ -32,8 +32,8 @@
     "dep-check": "aegir run dep-check",
     "release": "run-s build docs:no-publish npm:release docs",
     "npm:release": "aegir run release",
-    "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/client/README.md b/packages/client/README.md
@@ -4,23 +4,30 @@
   </a>
 </p>
 
-# @helia/delegated-routing-v1-http-api-client <!-- 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-delegated-routing-v1-http-api.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia-delegated-routing-v1-http-api)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia-delegated-routing-v1-http-api/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia-delegated-routing-v1-http-api/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > A Delegated Routing V1 HTTP API client
 
-A client implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) that can be used to interact with any compliant server implementation.
+## About
+
+A client implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/)
+that can be used to interact with any compliant server implementation.
+
+### Example
 
-## Table of contents <!-- omit in toc -->
+```typescript
+import { createRoutingV1HttpApiClient } from '@helia/routing-v1-http-api-client'
+import { CID } from 'multiformats/cid'
 
-- [Install](#install)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
+const client = createRoutingV1HttpApiClient(new URL('https://example.org'))
+
+for await (const prov of getProviders(CID.parse('QmFoo'))) {
+  // ...
+}
+```
 
 ## Install
 

diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -1,7 +1,8 @@
 /**
  * @packageDocumentation
  *
- * Create a client to use with a Routing V1 HTTP API server.
+ * A client implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/)
+ * that can be used to interact with any compliant server implementation.
  *
  * @example
  *

diff --git a/packages/client/typedoc.json b/packages/client/typedoc.json
@@ -1,5 +1,7 @@
 {
   "entryPoints": [
     "./src/index.ts"
-  ]
+  ],
+  "readme": "none",
+  "includeVersion": true
 }
diff --git a/packages/interop/README.md b/packages/interop/README.md
@@ -4,27 +4,13 @@
   </a>
 </p>
 
-# @helia/delegated-routing-v1-http-api-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-delegated-routing-v1-http-api.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia-delegated-routing-v1-http-api)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia-delegated-routing-v1-http-api/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia-delegated-routing-v1-http-api/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > Interop tests for the Delegated Routing V1 HTTP API server powered by Helia
 
-## Table of contents <!-- omit in toc -->
-
-- [Install](#install)
-- [License](#license)
-- [Contribute](#contribute)
-
-## Install
-
-```console
-$ npm i @helia/delegated-routing-v1-http-api-interop
-```
-
 ## License
 
 Licensed under either of

diff --git a/packages/interop/package.json b/packages/interop/package.json
@@ -22,12 +22,6 @@
     "!dist/test",
     "!**/*.tsbuildinfo"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
-    }
-  },
   "eslintConfig": {
     "extends": "ipfs",
     "parserOptions": {

diff --git a/packages/server/README.md b/packages/server/README.md
@@ -4,23 +4,64 @@
   </a>
 </p>
 
-# @helia/delegated-routing-v1-http-api-server <!-- 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-delegated-routing-v1-http-api.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia-delegated-routing-v1-http-api)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia-delegated-routing-v1-http-api/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia-delegated-routing-v1-http-api/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > A Delegated Routing V1 HTTP API server powered by Helia
 
-A server implementation of the IPFS [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/).
+## About
+
+Implements HTTP routes for a Fastify server that conform to the [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/).
+
+### Example
+
+```typescript
+import { createHelia } from 'helia'
+import { createRoutingV1HttpApiServer } from '@helia/routing-v1-http-api-server'
+
+const helia = await createHelia()
+const server = await createRoutingV1HttpApiServer(helia, {
+  listen: {
+    // fastify listen options
+  }
+})
+
+// now make http requests
+```
+
+Alternatively if you have a Fastify instance already you can add routes to it.
+,
+
+### Example
+
+```typescript
+import fastify from 'fastify'
+import cors from '@fastify/cors'
+import { createHelia } from 'helia'
+import routes from '@helia/routing-v1-http-api-server/routes'
+
+const server = fastify({
+ // fastify options
+})
+await server.register(cors, {
+  origin: '*',
+  methods: ['GET', 'OPTIONS'],
+  strictPreflight: false
+})
 
-## Table of contents <!-- omit in toc -->
+const helia = await createHelia()
 
-- [Install](#install)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
+// configure Routing V1 HTTP API routes
+routes(server, helia)
+
+await server.listen({
+  // fastify listen options
+})
+
+// now make http requests
+```
 
 ## Install
 

diff --git a/packages/server/src/routes/index.ts b/packages/server/src/routes/index.ts
@@ -1,3 +1,39 @@
+/**
+ * @packageDocumentation
+ *
+ * Configure your existing Fastify instance with routes that conform to the
+ * [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) spec.
+ *
+ * @example
+ *
+ * ```typescript
+ * import fastify from 'fastify'
+ * import cors from '@fastify/cors'
+ * import { createHelia } from 'helia'
+ * import routes from '@helia/routing-v1-http-api-server/routes'
+ *
+ * const server = fastify({
+ *  // fastify options
+ * })
+ * await server.register(cors, {
+ *   origin: '*',
+ *   methods: ['GET', 'OPTIONS'],
+ *   strictPreflight: false
+ * })
+ *
+ * const helia = await createHelia()
+ *
+ * // configure Routing V1 HTTP API routes
+ * routes(server, helia)
+ *
+ * await server.listen({
+ *   // fastify listen options
+ * })
+ *
+ * // now make http requests
+ * ```
+ */
+
 import getIpnsV1 from './routing/v1/ipns/get.js'
 import putIpnsV1 from './routing/v1/ipns/put.js'
 import getPeersV1 from './routing/v1/peers/get.js'

diff --git a/packages/server/typedoc.json b/packages/server/typedoc.json
@@ -2,5 +2,7 @@
   "entryPoints": [
     "./src/index.ts",
     "./src/routes/index.ts"
-  ]
+  ],
+  "readme": "none",
+  "includeVersion": true
 }
diff --git a/typedoc.json b/typedoc.json
@@ -1,4 +1,7 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "name": "Helia Routing V1 HTTP API"
+  "name": "Helia Routing V1 HTTP API",
+  "exclude": [
+    "packages/interop"
+  ]
 }