25 auto generate documentation from jsdoc (#29)

* update workflows to upload to GitHub Pages

* make all defined error types exportable

* update errors related types

* make more types exportable from api

* code refactoring, fix some documentation generation warnings

* define custom module names for documentation generation

* rename modules and code refactoring

* make setGitClientAgent util as internal

* add more JSDoc comments

* code refactoring

* update comments

* replace rmdir FsClient function with rm to allow recursive deletion

* add more JSDoc comments

* update some comments

* code refactoring

* add more JSDoc comments

* update browser usage example

* update package description and keywords

* add more comments

* add comments for BlobMergeCallback

* add more documentation for callback functions

* add documentation for ProgressCallback

* add documentation for AuthCallback

* update documentation

* add documentation for SignCallback

* add tests for custom conflict resolver

* add documentation for BlobMergeCallbackParams

* add more documentation for BlobMergeCallback

* add documentation for HttpClient

* update documentation for FsClient

* update documentation

* add documentation for Cache object

Author: alex-titarenko

.github/workflows/pull-request.yml

@@ -31,3 +31,6 @@ jobs:
 
       - name: Test (Browsers)
         run: npm run test:browsers
+
+      - name: Generate documentation
+        run: npm run gen-doc

.github/workflows/release.yml

@@ -4,6 +4,15 @@ on:
   push:
     branches: [ "main" ]
 
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   release:
     runs-on: macos-latest
@@ -32,7 +41,30 @@ jobs:
       - name: Test (Browsers)
         run: npm run test:browsers
 
-      - name: Publish
+      - name: Generate documentation
+        run: npm run gen-doc
+
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/
+
+      - name: Publish package
         run: npm publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: release
+
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

README.md

@@ -1,6 +1,10 @@
-# Git-Essentials
+# Git Essentials
 A collection of essential Git commands for your browser and Node.js.
 
+## Documentation
+
+Visit [https://noteshubapp.github.io/git-essentials](https://noteshubapp.github.io/git-essentials) to view the full documentation.
+
 ## Usage Examples
 
 ### Node.js
@@ -22,6 +26,9 @@ import { clone } from 'git-essentials'
 import { InMemoryFsClient } from 'git-essentials/clients/fs/InMemoryFsClient'
 import { makeWebHttpClient } from 'git-essentials/clients/request/WebHttpClient'
 
+// GitHub (like some other providers) does not return proper 'Access-Control-Allow-Origin' header
+// as a result the browser will refuse to serve the request.
+// To overcome this limitation CORS proxy server could be used.
 const corsProxyUrlTransformer = (originalUrl: string) => {
   return `https://www.noteshub.app/api/cors-proxy.ts?url=${encodeURIComponent(originalUrl)}`
 }

karma.conf.ts

@@ -43,7 +43,8 @@ module.exports = (config: any) => {
         "esModuleInterop": true,
         "baseUrl": ".",
         "paths": {
-          "git-essentials": ["./src/index"]
+          "git-essentials": ["./src/index"],
+          "git-essentials/*": ["./src/*"]
         }
       },
       bundlerOptions: {

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "git-essentials",
-  "version": "0.5.0",
-  "description": "The essential GIT commands",
+  "version": "0.6.0",
+  "description": "A collection of essential Git commands for your browser and Node.js",
   "main": "dist/esm/index.js",
   "types": "index.d.ts",
   "typesVersions": {
@@ -27,9 +27,6 @@
     "postbuild": "node ./scripts/fix-build.js",
     "test": "jest",
     "test:browser": "karma start",
-    "test:chrome": "karma start --single-run --browsers ChromeHeadless",
-    "test:webkit": "karma start --single-run --browsers WebkitHeadless",
-    "test:firefox": "karma start --single-run --browsers FirefoxHeadless",
     "test:browsers": "karma start --single-run --browsers ChromeHeadless,WebkitHeadless,FirefoxHeadless",
     "gen-doc": "npx typedoc",
     "gen-fs-fixture": "node ./scripts/gen-fs-fixture.js",
@@ -45,7 +42,12 @@
   },
   "keywords": [
     "git",
-    "js"
+    "js",
+    "typescript",
+    "nodejs",
+    "browser",
+    "isomorphic",
+    "isomorphic-javascript"
   ],
   "author": "Alex Titarenko",
   "license": "MIT",

package.json

@@ -11,17 +11,15 @@ import { _writeObject } from '../storage/writeObject'
 import { assertParameter } from '../utils/assertParameter'
 import { join } from '../utils/join'
 
+
 export type AddParams = {
   /** A file system implementation. */
   fs: FsClient
 
   /** A directory path. */
   dir: string
 
-  /**
-   * The git directory path.
-   * @defaultValue `join(dir, '.git')`
-   */
+  /** The git directory path (default: `{dir}/.git`). */
   gitdir?: string
 
   /** The path to the file to add to the index. */
@@ -36,14 +34,15 @@ export type AddParams = {
  *
  * @param args
  *
- * @returns Resolves successfully once the git index has been updated
+ * @returns Resolves successfully once the git index has been updated.
  *
  * @example
  * ```ts
  * await fs.writeFile('/tutorial/README.md', '# TEST')
  * await add({ fs, dir: '/tutorial', filepath: 'README.md' })
  * ```
  *
+ * @group Commands
  */
 export async function add({
   fs: _fs,

src/api/add.ts

@@ -4,14 +4,15 @@ import { FsClient } from '../models/FsClient'
 import { assertParameter } from '../utils/assertParameter'
 import { join } from '../utils/join'
 
-type AddRemoteParams = {
+
+export type AddRemoteParams = {
   /** A file system implementation. */
   fs: FsClient
 
   /** The working tree directory path. */
   dir: string
 
-  /**  The git directory path (default: `join(dir, '.git')`). */
+  /**  The git directory path (default: `{dir}/.git`). */
   gitdir?: string
 
   /** The name of the remote. */
@@ -27,19 +28,19 @@ type AddRemoteParams = {
 /**
  * Add or update a remote.
  *
- * @param {AddRemoteParams} args
+ * @param args
  *
- * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
+ * @returns Resolves successfully when filesystem operations are complete.
  *
  * @example
- * await git.addRemote({
+ * await addRemote({
  *   fs,
  *   dir: '/tutorial',
  *   remote: 'upstream',
- *   url: 'https://github.com/isomorphic-git/isomorphic-git'
+ *   url: 'https://github.com/NotesHubApp/git-essentials'
  * })
- * console.log('done')
  *
+ * @group Commands
  */
 export async function addRemote({
   fs,

src/api/addRemote.ts

@@ -5,14 +5,14 @@ import { assertParameter } from '../utils/assertParameter'
 import { join } from '../utils/join'
 
 
-type BranchParams = {
+export type BranchParams = {
   /** A file system implementation. */
   fs: FsClient
 
   /** The working tree directory path. */
   dir: string
 
-  /** The git directory path (default: `join(dir, '.git')`). */
+  /** The git directory path (default: `{dir}/.git`). */
   gitdir?: string
 
   /** What to name the branch. */
@@ -31,14 +31,14 @@ type BranchParams = {
 /**
  * Create a branch.
  *
- * @param {BranchParams} args
+ * @param args
  *
- * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
+ * @returns Resolves successfully when filesystem operations are complete.
  *
  * @example
- * await git.branch({ fs, dir: '/tutorial', ref: 'develop' })
- * console.log('done')
+ * await branch({ fs, dir: '/tutorial', ref: 'develop' })
  *
+ * @group Commands
  */
 export async function branch({
   fs,

src/api/branch.ts

@@ -6,7 +6,8 @@ import { join } from '../utils/join'
 import { FsClient } from '../models/FsClient'
 import { ProgressCallback } from '../models'
 
-type CheckoutParams = {
+
+export type CheckoutParams = {
   /** A file system implementation. */
   fs: FsClient
 
@@ -16,7 +17,7 @@ type CheckoutParams = {
   /** The working tree directory path. */
   dir: string
 
-  /** The git directory path (default: `join(dir, '.git')`). */
+  /** The git directory path (default: `{dir}/.git`). */
   gitdir?: string
 
   /** Which remote repository to use (default: `origin`). */
@@ -52,40 +53,39 @@ type CheckoutParams = {
  *
  * If the branch already exists it will check out that branch. Otherwise, it will create a new remote tracking branch set to track the remote branch of that name.
  *
- * @param {CheckoutParams} args
+ * @param args
  *
- * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
+ * @returns Resolves successfully when filesystem operations are complete.
  *
  * @example
  * // switch to the main branch
- * await git.checkout({
+ * await checkout({
  *   fs,
  *   dir: '/tutorial',
  *   ref: 'main'
  * })
- * console.log('done')
  *
  * @example
  * // restore the 'docs' and 'src/docs' folders to the way they were, overwriting any changes
- * await git.checkout({
+ * await checkout({
  *   fs,
  *   dir: '/tutorial',
  *   force: true,
  *   filepaths: ['docs', 'src/docs']
  * })
- * console.log('done')
  *
  * @example
  * // restore the 'docs' and 'src/docs' folders to the way they are in the 'develop' branch, overwriting any changes
- * await git.checkout({
+ * await checkout({
  *   fs,
  *   dir: '/tutorial',
  *   ref: 'develop',
  *   noUpdateHead: true,
  *   force: true,
  *   filepaths: ['docs', 'src/docs']
  * })
- * console.log('done')
+ *
+ * @group Commands
  */
 export async function checkout({
   fs,