add typedoc, test doc generation (#588)

* add typedoc, test doc generation

* add markdown plugin, add md rendered docs

* ignore src/generated from doc generation

* add docs ci workflow for publishing

* add flow to PR

* odd npm doc:publish script

* remove old docs/api path

* test preview page deploy

* ignore generated html

* remove preview

* ignore docs for eslint

* add plugin for missing exports (not explicitly exported but used by exported types)

* disable sources

* test commiting new api docs on prepublish

* test modifying repo docs on push (before testing on prerelease flow)

* add action/checkout@v4 to publish docs api to repo

* change order of steps to have node and npm

* fix stuff

* git user setup

* remove unnecessary step, remove git fetch

* use external action to update repo

* allow gh action to write repo (!!)

* update docs/README.md to point to md api

* Update api markdown docs

* remove api doc generation on every push (in docs.yml), move action to release.yml

* fix: accidentally removd actions/checkout on docs.yml

* forgot to add `npm ci` to docs.yml

* Apply suggestions from code review

Co-authored-by: Evan Hahn <[email protected]>

---------

Co-authored-by: Tomás Ciccola <[email protected]>
Co-authored-by: tomasciccola <[email protected]>
Co-authored-by: Evan Hahn <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Publish documentation
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  publish-documentation:
+    permissions:
+      id-token: write
+      pages: write
+      contents: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Generate HTML documentation
+        run: |
+          npm ci
+          npm run doc:publish
+      - id: upload-documentation
+        name: Upload documentation to Pages
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/api/html
+      - id: deployment
+        name: Deploy documentation to GitHub Pages
+        uses: actions/deploy-pages@v2

.github/workflows/release.yml

@@ -32,6 +32,18 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: 18
+      - uses: actions/checkout@v4
+      - name: Set git user
+        uses: fregante/setup-git-user@v1
+      - name: Generate Api docs
+        run: |
+          npm ci
+          npm run doc
+      - name: Push updated markdown docs
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: 'docs: update API docs'
+          file_pattern: 'docs/api/md/*'
       - uses: nearform-actions/optic-release-automation-action@v4
         with:
           commit-message: 'Release {version}'

.gitignore

@@ -7,3 +7,4 @@ proto/build
 /dist
 !/drizzle/**/*.sql
 .eslintcache
+docs/api/html/*

docs/README.md

@@ -6,7 +6,7 @@ In most cases you'll be using the [mobile](https://github.com/digidem/mapeo-mobi
 
 ## API reference
 
-Get detailed information about the classes, methods, function, and types of Mapeo Core in the [API docs](./api/).
+Get detailed information about the classes, methods, function, and types of Mapeo Core in the [API docs](./api/md/).
 
 ## Developing
 

docs/api/md/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

docs/api/md/README.md

@@ -0,0 +1,71 @@
+API
+
+# API
+
+## Table of contents
+
+### Modules
+
+- [\<internal\>](modules/internal_.md)
+
+### Classes
+
+- [FastifyController](classes/FastifyController.md)
+- [MapeoManager](classes/MapeoManager.md)
+
+### Functions
+
+- [MapeoMapsFastifyPlugin](README.md#mapeomapsfastifyplugin)
+- [MapeoOfflineFallbackMapFastifyPlugin](README.md#mapeoofflinefallbackmapfastifyplugin)
+- [MapeoStaticMapsFastifyPlugin](README.md#mapeostaticmapsfastifyplugin)
+
+## Functions
+
+### MapeoMapsFastifyPlugin
+
+▸ **MapeoMapsFastifyPlugin**(`instance`, `opts`): `Promise`\<`void`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `instance` | `FastifyInstance`\<`RawServerDefault`, `IncomingMessage`, `ServerResponse`\<`IncomingMessage`\>, `FastifyBaseLogger`, `FastifyTypeProviderDefault`\> |
+| `opts` | [`MapsPluginOpts`](interfaces/internal_.MapsPluginOpts.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+___
+
+### MapeoOfflineFallbackMapFastifyPlugin
+
+▸ **MapeoOfflineFallbackMapFastifyPlugin**(`instance`, `opts`): `Promise`\<`void`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `instance` | `FastifyInstance`\<`RawServerDefault`, `IncomingMessage`, `ServerResponse`\<`IncomingMessage`\>, `FastifyBaseLogger`, `FastifyTypeProviderDefault`\> |
+| `opts` | [`OfflineFallbackMapPluginOpts`](interfaces/internal_.OfflineFallbackMapPluginOpts.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+___
+
+### MapeoStaticMapsFastifyPlugin
+
+▸ **MapeoStaticMapsFastifyPlugin**(`instance`, `opts`): `Promise`\<`void`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `instance` | `FastifyInstance`\<`RawServerDefault`, `IncomingMessage`, `ServerResponse`\<`IncomingMessage`\>, `FastifyBaseLogger`, `FastifyTypeProviderDefault`\> |
+| `opts` | [`StaticMapsPluginOpts`](interfaces/internal_.StaticMapsPluginOpts.md) |
+
+#### Returns
+
+`Promise`\<`void`\>

docs/api/md/classes/FastifyController.md

@@ -0,0 +1,68 @@
+[API](../README.md) / FastifyController
+
+# Class: FastifyController
+
+## Table of contents
+
+### Constructors
+
+- [constructor](FastifyController.md#constructor)
+
+### Methods
+
+- [start](FastifyController.md#start)
+- [started](FastifyController.md#started)
+- [stop](FastifyController.md#stop)
+
+## Constructors
+
+### constructor
+
+• **new FastifyController**(`opts`): [`FastifyController`](FastifyController.md)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `opts` | `Object` |
+| `opts.fastify` | `FastifyInstance`\<`RawServerDefault`, `IncomingMessage`, `ServerResponse`\<`IncomingMessage`\>, `FastifyBaseLogger`, `FastifyTypeProviderDefault`\> |
+
+#### Returns
+
+[`FastifyController`](FastifyController.md)
+
+## Methods
+
+### start
+
+▸ **start**(`opts?`): `Promise`\<`void`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `opts?` | [`StartOpts`](../interfaces/internal_.StartOpts.md) |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+___
+
+### started
+
+▸ **started**(): `Promise`\<`void`\>
+
+#### Returns
+
+`Promise`\<`void`\>
+
+___
+
+### stop
+
+▸ **stop**(): `Promise`\<`void`\>
+
+#### Returns
+
+`Promise`\<`void`\>