Adopt typedoc for API docs (#66), closes #63

* Build the API docs when the site is being built

* Add watch:docs command

* Add a custom CSS stub file

* Use a custom index page for the API docs

* Add support for the abstract tag

* Hide the protected and external filters since we don't have such modifiers

* Update inline docs so that Typedoc parses them correctly

* Add (partial) support for Prism

In Typedoc, we can use no extensibility point [1] to replace the built-in syntax highlighter (Shiki) with Prism. The only way to do that is to write a custom theme that (somehow) uses another syntax highlighter or doesn't highlight code blocks at all. I tried but failed — there's a ton of stuff to know to be able to do that (at least from my perspective).

However, we can make the built-in markdown plugin (Marked) use a custom highlight function instead of the one that calls the Typedoc built-in syntax highlighter. That means that our markdown files and code blocks in the code comments (Typedoc supports markdown in comments) can be highlighted by Prism.

[1] https://discord.com/channels/508357248330760243/829307039447515176/1202594912051273848

.eleventyignore

@@ -1 +1,2 @@
-**/contributing.md
+**/contributing.md
+API.md

API.md

@@ -0,0 +1 @@
+## Index page for the API documentation

README.md

@@ -1,6 +1,6 @@
 <header class="home no-home-link">
 
-<img src="logo.svg" width="100" alt="Logo showing a cloud presented as a tree" />
+<img src="/logo.svg" width="100" alt="Logo showing a cloud presented as a tree" />
 
 <h1 class="logo"><span class="ma">ma</span>data</h1>
 

api.postcss

@@ -0,0 +1,3 @@
+/*
+	Custom CSS for the API docs goes here...
+*/

backends/basic/element.js

@@ -1,11 +1,12 @@
-/**
- * Save in an HTML element
- * @class Element
- */
-
 import Backend from "../../src/backend.js";
 import {$} from "../../src/util.js";
 
+/**
+ * Read and write data into an HTML element.
+ * @class Element
+ * @extends Backend
+ * @category Basic
+ */
 export default class Element extends Backend {
 	constructor (url, o) {
 		super(url, o);

backends/basic/local.js

@@ -1,10 +1,12 @@
-/**
- * Store data in localStorage
- * @class Local
- */
 import Backend from "../../src/backend.js";
 import { localStorage } from "../../src/node-shims.js";
 
+/**
+ * Store data in the browser's localStorage.
+ * @class Local
+ * @extends Backend
+ * @category Basic
+ */
 export default class Local extends Backend {
 	constructor (url, o) {
 		super(url, o);

backends/basic/remote.js

@@ -1,9 +1,11 @@
+import Backend from "../../src/backend.js";
+
 /**
+ * Load the URL as a remote resource. No save.
  * @class Remote
- * Load from a remote URL, no save
+ * @extends Backend
+ * @category Basic
  */
-import Backend from "../../src/backend.js";
-
 export default class Remote extends Backend {
 	constructor (url, o) {
 		super(url, o);

backends/coda/api/coda-api.js

@@ -1,5 +1,10 @@
 import Coda from "../coda.js";
 
+/**
+ * @class CodaAPI
+ * @extends Coda
+ * @category Coda
+ */
 export default class CodaAPI extends Coda {
 	async get (ref = this.ref) {
 		return this.request(ref.url);

backends/coda/coda.js

@@ -1,9 +1,10 @@
+import OAuthBackend from "../../src/oauth-backend.js";
+
 /**
  * @class Coda
  * @extends OAuthBackend
+ * @category Coda
  */
-import OAuthBackend from "../../src/oauth-backend.js";
-
 export default class Coda extends OAuthBackend {
 	constructor (url, o) {
 		super(url, o);

backends/coda/table/coda-table.js

@@ -1,5 +1,10 @@
 import Coda from "../coda.js";
 
+/**
+ * @class CodaTable
+ * @extends Coda
+ * @category Coda
+ */
 export default class CodaTable extends Coda {
 	async get (ref = this.ref) {
 		if (!ref.tableId) {

backends/dropbox/index.js

@@ -1,9 +1,10 @@
+import OAuthBackend from "../../src/oauth-backend.js";
+
 /**
+ * Dropbox backend.
  * @class Dropbox
  * @extends OAuthBackend
  */
-import OAuthBackend from "../../src/oauth-backend.js";
-
 export default class Dropbox extends OAuthBackend {
 	static apiDomain = "https://api.dropboxapi.com/2/";
 	static oAuth = "https://www.dropbox.com/oauth2/authorize";

backends/firebase/index.js

@@ -1,8 +1,3 @@
-/**
- * Firebase backend.
- * @class Firebase
- * @extends OAuthBackend
- */
 import AuthBackend from "../../src/auth-backend.js";
 import { readFile, toArray } from "../../src/util.js";
 
@@ -11,6 +6,11 @@ import { getAuth, onAuthStateChanged, signInWithPopup, signOut, GoogleAuthProvid
 import { getFirestore, doc, collection, getDoc, getDocs, setDoc, addDoc, deleteDoc } from "https://www.gstatic.com/firebasejs/10.5.0/firebase-firestore-lite.js";
 import { getStorage, ref, uploadString, getDownloadURL, deleteObject } from "https://www.gstatic.com/firebasejs/10.5.0/firebase-storage.js";
 
+/**
+ * Firebase backend.
+ * @class Firebase
+ * @extends OAuthBackend
+ */
 export default class Firebase extends AuthBackend {
 	constructor (url, o) {
 		super(url, o);

backends/github/api/github-api.js

@@ -1,6 +1,12 @@
 import Github from "../github.js";
 // import hooks from "../../../src/hooks.js";
 
+/**
+ * Backend for performing raw API calls with the REST or GraphQL API to GitHub repositories.
+ * @class GithubAPI
+ * @extends Github
+ * @category GitHub
+ */
 export default class GithubAPI extends Github {
 	update (url, o) {
 		super.update(url, o);

backends/github/file/github-file.js

@@ -1,11 +1,13 @@
-/**
- * @class GithubFile
- * @extends Github
- */
 import Github from "../github.js";
 import hooks from "../../../src/hooks.js";
 import {readFile, delay} from "../../../src/util.js";
 
+/**
+ * Backend for reading and writing data and uploading files in GitHub repositories.
+ * @class GithubFile
+ * @extends Github
+ * @category GitHub
+ */
 export default class GithubFile extends Github {
 	static fileBased = true;
 

backends/github/gist/github-gist.js

@@ -1,11 +1,12 @@
+import Github from "../github.js";
+import hooks from "../../../src/hooks.js";
+
 /**
- * Github Gist backend
+ * Github Gist backend.
  * @class GithubGist
  * @extends Github
+ * @category GitHub
  */
-import Github from "../github.js";
-import hooks from "../../../src/hooks.js";
-
 export default class GithubGist extends Github {
 	async get (file = this.ref) {
 		if (this.isAuthenticated()) {

backends/github/github.js

@@ -1,9 +1,11 @@
+import OAuthBackend from "../../src/oauth-backend.js";
+
 /**
+ * Base class for all Github backends, containing auth methods.
  * @class Github
  * @extends OAuthBackend
+ * @category GitHub
  */
-import OAuthBackend from "../../src/oauth-backend.js";
-
 export default class Github extends OAuthBackend {
 	constructor (url, o) {
 		super(url, o);

backends/google/calendar/google-calendar.js

@@ -1,10 +1,11 @@
+import Google from "../google.js";
+
 /**
  * Google Calendar backend. Read-only for now.
  * @class GoogleCalendar
  * @extends Google
+ * @category Google
  */
-import Google from "../google.js";
-
 export default class GoogleCalendar extends Google {
 	async get (ref = this.ref) {
 		let call = `${ref.calendarId}/events?key=${this.apiKey}`;

backends/google/drive/google-drive.js

@@ -1,9 +1,11 @@
+import Google from "../google.js";
+
 /**
+ * Google Drive backend.
  * @class GoogleDrive
  * @extends Google
+ * @category Google
  */
-import Google from "../google.js";
-
 export default class GoogleDrive extends Google {
 	static apiDomain = "https://www.googleapis.com/";
 	static scopes = ["https://www.googleapis.com/auth/drive", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/userinfo.email"];

backends/google/google.js

@@ -1,10 +1,11 @@
+import OAuthBackend from "../../src/oauth-backend.js";
+
 /**
- * Base class for all Google backends, containing auth methods
+ * Base class for all Google backends, containing auth methods.
  * @class Google
  * @extends OAuthBackend
+ * @category Google
  */
-import OAuthBackend from "../../src/oauth-backend.js";
-
 export default class Google extends OAuthBackend {
 	constructor (url, o) {
 		super(url, o);

backends/google/sheets/google-sheets.js

@@ -1,10 +1,11 @@
+import Google from "../google.js";
+
 /**
  * Google Sheets backend.
  * @class GoogleSheets
  * @extends Google
+ * @category Google
  */
-import Google from "../google.js";
-
 export default class GoogleSheets extends Google {
 	/**
 	 * Read data from the spreadsheet.

backends/index-fn.js

@@ -1,6 +1,6 @@
 /**
+ * Export all backends without side effects.
  * @module index-fn
- * Export all backends without side effects
  */
 
 export * from "./basic/index.js";

backends/index.js

@@ -1,6 +1,6 @@
 /**
- * @module index
- * Export all backends and register them
+ * Export all backends and register them.
+ * @module Backends
  */
 import Backend from "../src/backend.js";
 import * as backends from "./index-fn.js";

formats/csv/index.js

@@ -1,6 +1,10 @@
 import Format from "../../src/format.js";
 import { parse, stringify } from "../../lib/csv/dist/esm/sync.js";
 
+/**
+ * @class CSV
+ * @extends Format
+ */
 export default class CSV extends Format {
 	static defaultOptions = {
 		parse: {

formats/index-fn.js

@@ -1,6 +1,6 @@
 /**
+ * Export all formats without side effects.
  * @module formats/index-fn
- * Export all formats without side effects
  */
 
 export {default as JSON} from "./json/index.js";

formats/index.js

@@ -1,6 +1,6 @@
 /**
- * @module formats/index
- * Export all formats and register them
+ * Export all formats and register them.
+ * @module Formats
  */
 import Format from "../src/format.js";
 import * as formats from "./index-fn.js";

formats/json/index.js

@@ -1,5 +1,9 @@
 import Format from "../../src/format.js";
 
+/**
+ * @class JSON
+ * @extends Format
+ */
 export default class JSON extends Format {
 	static defaultOptions = {
 		stringify: {

formats/text/index.js

@@ -1,5 +1,9 @@
 import Format from "../../src/format.js";
 
+/**
+ * @class Text
+ * @extends Format
+ */
 export default class Text extends Format {
 	static extensions = ["txt", "md"];
 	static mimeTypes = ["text/plain"];

formats/yaml/index.js

@@ -1,6 +1,10 @@
 import Format from "../../src/format.js";
 import { parse, stringify } from "../../lib/yaml/browser/index.js";
 
+/**
+ * @class YAML
+ * @extends Format
+ */
 export default class YAML extends Format {
 	static extensions = ["yaml", "yml"];
 	static mimeTypes = ["application/yaml", "application/x-yaml", "text/yaml"];