chore: auto-generate the alphabetical function lists (#1031)

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,25 +7,21 @@
 - [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
 - [ ] squash merge the PR with commit message "fix: [Description of fix]"
 
-## I'm adding a parameter to an existing command:
+## I'm adding a parameter to an existing command X:
 
-- [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
-- [ ] add parameter to the function in `src/commands/X.js`
+- [ ] add parameter to the function in `src/api/X.js` (and `src/commands/X.js` if necessary)
 - [ ] document the parameter in the JSDoc comment above the function
-- [ ] add parameter to the TypeScript library definition for X in `src/index.d.ts`
 - [ ] add a test case in `__tests__/test-X.js` if possible
-- [ ] squash merge the PR with commit message "feat: Added 'bar' parameter to X command"
+- [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
+- [ ] squash merge the PR with commit message "feat(X): Added 'bar' parameter"
 
 ## I'm adding a new command:
 
-- [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
-- [ ] add as a new file in `src/commands`
+- [ ] add as a new file in `src/api` (and `src/commands` if necessary)
 - [ ] add command to `src/index.js`
-- [ ] add TypeScript definition in `src/index.d.ts`
 - [ ] update `__tests__/__snapshots__/test-exports.js.snap`
-- [ ] add command to README list of commands
 - [ ] create a test in `src/__tests__`
 - [ ] document the command with a JSDoc comment
-  - [ ] add page to the [Alphabetical Index](https://github.com/isomorphic-git/isomorphic-git.github.io/blob/source/docs/alphabetic.md)
-  - [ ] add page to the [sidebar](https://github.com/isomorphic-git/isomorphic-git.github.io/blob/source/website/sidebars.json)
+- [ ] add page to the Docs Sidebar `website/sidebars.json`
+- [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
 - [ ] squash merge the PR with commit message "feat: Added 'X' command"

CONTRIBUTING.md

@@ -6,33 +6,29 @@ You are very welcome here and any contribution is appreciated. :+1:
 
 # Tips
 
-The code is written in "plain" JavaScript and as a rule of thumb shouldn't require transpilation. (The glaring exception being browser's lack of support for bare imports.) However, until recently Webpack and Jest threw a parse error when they encountered object spread properties (like `{... args}`). So for now I ask that you use `Object.assign`. Too many people ran into issues with object spread. See https://gitter.im/isomorphic-git/Lobby?at=5bd8a0ed435c2a518e2cc779 for background. We'll upgrade all the Object.assign uses to object spread properties when we do a breaking release.
+The code is written in "plain" JavaScript and as a rule of thumb shouldn't require transpilation. (The glaring exception being browser's lack of support for bare imports.)
 
 ## New feature checklists :sparkles:️
 I'm honestly documenting these steps just so I don't forget them myself.
 
 To add a parameter to an existing command `X`:
 
-- [ ] add parameter to the function in `src/commands/X.js`
-- [ ] add parameter to [docs](https://github.com/isomorphic-git/isomorphic-git.github.io/tree/source/docs)/X.md
-- [ ] add parameter to the TypeScript library definition for X in `src/index.d.ts`
+- [ ] add parameter to the function in `src/api/X.js` (and `src/commands/X.js` if necessary)
+- [ ] document the parameter in the JSDoc comment above the function
 - [ ] add a test case in `__tests__/test-X.js` if possible
 - [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
-- [ ] make a feature commit "feat: Added 'bar' parameter to X command"
+- [ ] squash merge the PR with commit message "feat(X): Added 'bar' parameter"
 
 To create a new command:
 
-- [ ] add as a new file in `src/commands`
+- [ ] add as a new file in `src/api` (and `src/commands` if necessary)
 - [ ] add command to `src/index.js`
-- [ ] add TypeScript definition in `src/index.d.ts`
 - [ ] update `__tests__/__snapshots__/test-exports.js.snap`
-- [ ] add command to README list of commands
 - [ ] create a test in `src/__tests__`
-- [ ] create a new doc page [docs](https://github.com/isomorphic-git/isomorphic-git.github.io/tree/source/docs)/X.md
-  - [ ] add page to the [Alphabetical Index](https://github.com/isomorphic-git/isomorphic-git.github.io/blob/source/docs/alphabetic.md)
-  - [ ] add page to the [sidebar](https://github.com/isomorphic-git/isomorphic-git.github.io/blob/source/website/sidebars.json)
+- [ ] document the command with a JSDoc comment
+- [ ] add page to the Docs Sidebar `website/sidebars.json`
 - [ ] if this is your first time contributing, run `npm run add-contributor` and follow the prompts to add yourself to the README
-- [ ] make a feature commit "feat: Added 'X' command"
+- [ ] squash merge the PR with commit message "feat: Added 'X' command"
 
 # Overview
 

README.md

@@ -70,6 +70,7 @@ At the time of writing, the following breaking changes are planned:
 - [ ] Oh, and I should move all the error strings into a separate JSON file that can be fetched lazily in production.
 - [ ] I should probably remove `username`, `password`, `token`, and `oauth2format` and make everyone use `onAuth` callback for that.
 - [ ] Fix `push` to use the remote tracking branch by default for `remtoeRef`
+- [x] Auto-generate `docs/alphabetic.md` and `README` list from filenames in `src/api`.
 
 ## Getting Started
 
@@ -170,6 +171,12 @@ unless there is a major version bump.
 
 ### commands
 
+<!-- API-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+
+<!-- autogenerated_by: __tests__/__helpers__/generate-docs.js -->
+
 - [add](https://isomorphic-git.github.io/docs/add.html)
 - [addNote](https://isomorphic-git.github.io/docs/addNote.html)
 - [addRemote](https://isomorphic-git.github.io/docs/addRemote.html)
@@ -178,7 +185,6 @@ unless there is a major version bump.
 - [checkout](https://isomorphic-git.github.io/docs/checkout.html)
 - [clone](https://isomorphic-git.github.io/docs/clone.html)
 - [commit](https://isomorphic-git.github.io/docs/commit.html)
-- [config](https://isomorphic-git.github.io/docs/config.html)
 - [currentBranch](https://isomorphic-git.github.io/docs/currentBranch.html)
 - [deleteBranch](https://isomorphic-git.github.io/docs/deleteBranch.html)
 - [deleteRef](https://isomorphic-git.github.io/docs/deleteRef.html)
@@ -187,7 +193,10 @@ unless there is a major version bump.
 - [expandOid](https://isomorphic-git.github.io/docs/expandOid.html)
 - [expandRef](https://isomorphic-git.github.io/docs/expandRef.html)
 - [fetch](https://isomorphic-git.github.io/docs/fetch.html)
+- [findMergeBase](https://isomorphic-git.github.io/docs/findMergeBase.html)
 - [findRoot](https://isomorphic-git.github.io/docs/findRoot.html)
+- [getConfig](https://isomorphic-git.github.io/docs/getConfig.html)
+- [getConfigAll](https://isomorphic-git.github.io/docs/getConfigAll.html)
 - [getRemoteInfo](https://isomorphic-git.github.io/docs/getRemoteInfo.html)
 - [hashBlob](https://isomorphic-git.github.io/docs/hashBlob.html)
 - [indexPack](https://isomorphic-git.github.io/docs/indexPack.html)
@@ -205,15 +214,15 @@ unless there is a major version bump.
 - [push](https://isomorphic-git.github.io/docs/push.html)
 - [readBlob](https://isomorphic-git.github.io/docs/readBlob.html)
 - [readCommit](https://isomorphic-git.github.io/docs/readCommit.html)
+- [readNote](https://isomorphic-git.github.io/docs/readNote.html)
 - [readObject](https://isomorphic-git.github.io/docs/readObject.html)
 - [readTag](https://isomorphic-git.github.io/docs/readTag.html)
 - [readTree](https://isomorphic-git.github.io/docs/readTree.html)
 - [remove](https://isomorphic-git.github.io/docs/remove.html)
 - [removeNote](https://isomorphic-git.github.io/docs/removeNote.html)
 - [resetIndex](https://isomorphic-git.github.io/docs/resetIndex.html)
 - [resolveRef](https://isomorphic-git.github.io/docs/resolveRef.html)
-- [showNote](https://isomorphic-git.github.io/docs/showNote.html)
-- [sign](https://isomorphic-git.github.io/docs/sign.html)
+- [setConfig](https://isomorphic-git.github.io/docs/setConfig.html)
 - [status](https://isomorphic-git.github.io/docs/status.html)
 - [statusMatrix](https://isomorphic-git.github.io/docs/statusMatrix.html)
 - [tag](https://isomorphic-git.github.io/docs/tag.html)
@@ -223,9 +232,13 @@ unless there is a major version bump.
 - [writeBlob](https://isomorphic-git.github.io/docs/writeBlob.html)
 - [writeCommit](https://isomorphic-git.github.io/docs/writeCommit.html)
 - [writeObject](https://isomorphic-git.github.io/docs/writeObject.html)
+- [writeRef](https://isomorphic-git.github.io/docs/writeRef.html)
 - [writeTag](https://isomorphic-git.github.io/docs/writeTag.html)
 - [writeTree](https://isomorphic-git.github.io/docs/writeTree.html)
-- [writeRef](https://isomorphic-git.github.io/docs/writeRef.html)
+
+<!-- markdownlint-enable -->
+<!-- prettier-ignore-end -->
+<!-- API-LIST:END -->
 
 ## Community
 

__tests__/__helpers__/generate-docs.js

@@ -3,8 +3,10 @@ const fs = require('fs')
 const path = require('path')
 const table = require('markdown-table')
 const git = require('../..')
+const { E } = require('../..')
 
 const dir = path.join(__dirname, '..', '..')
+const thisFile = path.relative(dir, __filename)
 const ref = process.argv[2] || 'HEAD'
 
 function cleanType (type) {
@@ -294,10 +296,56 @@ async function gendoc (file, filepath) {
   gitignoreContent += docs.join('\n') + '\n'
   fs.writeFileSync(gitignorePath, gitignoreContent, 'utf8')
 
-  // Generate errors.md
-  const { E } = require('../..')
-  const thisFile = path.relative(dir, __filename)
+  // Generate alphabetic.md
+  {
+    const alphabeticFile = path.join(
+      __dirname,
+      '..',
+      '..',
+      'docs',
+      'alphabetic.md'
+    )
+    const contents = `---
+title: All Commands
+sidebar_label: Alphabetical Index
+---
+<!-- autogenerated_by: ${thisFile} -->
+
+${docs
+    .map(doc => doc.replace(/^docs\/(.*)\.md$/, '$1'))
+    .map(doc => `- [${doc}](${doc})`)
+    .join('\n')}
+
+# Errors
+(added here so Algolia indexes the page)
+- [Error Code Index](errors)
+`
+    fs.writeFileSync(alphabeticFile, contents)
+  }
 
+  // Update alphabetic listing in README.md
+  {
+    const readmeFile = path.join(__dirname, '..', '..', 'README.md')
+    const commandList = `API-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+
+<!-- autogenerated_by: ${thisFile} -->
+
+${docs
+    .map(doc => doc.replace(/^docs\/(.*)\.md$/, '$1'))
+    .map(doc => `- [${doc}](https://isomorphic-git.github.io/docs/${doc}.html)`)
+    .join('\n')}
+
+<!-- markdownlint-enable -->
+<!-- prettier-ignore-end -->
+<!-- API-LIST:END`
+    let content = fs.readFileSync(readmeFile, 'utf8')
+    content = content.replace(/API-LIST:START(.|\n)+API-LIST:END/m, commandList)
+    fs.writeFileSync(readmeFile, content)
+  }
+
+  // Generate errors.md
   const docFile = path.join(__dirname, '..', '..', 'docs', 'errors.md')
   const { blob } = await git.readBlob({
     fs,

docs/alphabetic.md

@@ -2,6 +2,7 @@
 title: All Commands
 sidebar_label: Alphabetical Index
 ---
+<!-- autogenerated_by: __tests__/__helpers__/generate-docs.js -->
 
 - [add](add)
 - [addNote](addNote)
@@ -11,7 +12,6 @@ sidebar_label: Alphabetical Index
 - [checkout](checkout)
 - [clone](clone)
 - [commit](commit)
-- [config](config)
 - [currentBranch](currentBranch)
 - [deleteBranch](deleteBranch)
 - [deleteRef](deleteRef)
@@ -20,7 +20,10 @@ sidebar_label: Alphabetical Index
 - [expandOid](expandOid)
 - [expandRef](expandRef)
 - [fetch](fetch)
+- [findMergeBase](findMergeBase)
 - [findRoot](findRoot)
+- [getConfig](getConfig)
+- [getConfigAll](getConfigAll)
 - [getRemoteInfo](getRemoteInfo)
 - [hashBlob](hashBlob)
 - [indexPack](indexPack)
@@ -29,8 +32,8 @@ sidebar_label: Alphabetical Index
 - [listBranches](listBranches)
 - [listFiles](listFiles)
 - [listNotes](listNotes)
-- [listTags](listTags)
 - [listRemotes](listRemotes)
+- [listTags](listTags)
 - [log](log)
 - [merge](merge)
 - [packObjects](packObjects)
@@ -46,29 +49,19 @@ sidebar_label: Alphabetical Index
 - [removeNote](removeNote)
 - [resetIndex](resetIndex)
 - [resolveRef](resolveRef)
-- [STAGE](STAGE)
+- [setConfig](setConfig)
 - [status](status)
 - [statusMatrix](statusMatrix)
 - [tag](tag)
-- [TREE](TREE)
 - [verify](verify)
 - [version](version)
 - [walk](walk)
-- [WORKDIR](WORKDIR)
 - [writeBlob](writeBlob)
 - [writeCommit](writeCommit)
 - [writeObject](writeObject)
+- [writeRef](writeRef)
 - [writeTag](writeTag)
 - [writeTree](writeTree)
-- [writeRef](writeRef)
-
-# Plugins
-
-- [credentialManager](plugin_credentialManager)
-- [emitter](plugin_emitter)
-- [fs](plugin_fs)
-- [http](plugin_http)
-- [pgp](plugin_pgp)
 
 # Errors
 (added here so Algolia indexes the page)

src/api/removeNote.js

@@ -18,7 +18,7 @@ import { normalizeCommitterObject } from '../utils/normalizeCommitterObject.js'
  * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
  * @param {string} [args.ref] - The notes ref to look under
- * @param {string} args.oid - [required] The SHA-1 object id of the object to remove the note from.
+ * @param {string} args.oid - The SHA-1 object id of the object to remove the note from.
  * @param {Object} [args.author] - The details about the author.
  * @param {string} [args.author.name] - Default is `user.name` config.
  * @param {string} [args.author.email] - Default is `user.email` config.

website/i18n/en.json

@@ -45,10 +45,6 @@
         "title": "commit",
         "sidebar_label": "commit"
       },
-      "config": {
-        "title": "config",
-        "sidebar_label": "config"
-      },
       "currentBranch": {
         "title": "currentBranch",
         "sidebar_label": "currentBranch"