Skip to content

Commit 43711e4

Browse files
baileympearsonbaileympearson
authored
chore(NODE-4018): add doc generation scripts and template to main (#3153)
1 parent 446da95 commit 43711e4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+11620
-8
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,6 @@ serverless.env
6767

6868
lb-expansion.yml
6969
lb.env
70+
71+
# docs specific configuration
72+
etc/docs/build

‎README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
The official [MongoDB](https://www.mongodb.com/) driver for Node.js.
44

5-
**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/CHANGES_4.0.0.md)!**
5+
**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_4.0.0.md)!**
66

77
## Quick Links
88

@@ -14,7 +14,7 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js.
1414
| source | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) |
1515
| mongodb | [www.mongodb.com](https://www.mongodb.com) |
1616
| changelog | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md) |
17-
| upgrade to v4 | [docs/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/CHANGES_4.0.0.md) |
17+
| upgrade to v4 | [etc/notes/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_4.0.0.md) |
1818
| contributing | [CONTRIBUTING.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTING.md) |
1919

2020
### Bugs / Feature Requests
@@ -79,7 +79,7 @@ The MongoDB driver depends on several other packages. These are:
7979
- [kerberos](https://github.com/mongodb-js/kerberos)
8080
- [mongodb-client-encryption](https://github.com/mongodb/libmongocrypt#readme)
8181

82-
Some of these packages include native C++ extensions. Consult the [trouble shooting guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/native-extensions.md) if you run into issues.
82+
Some of these packages include native C++ extensions. Consult the [trouble shooting guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/native-extensions.md) if you run into issues.
8383

8484
## Quick Start
8585

@@ -240,7 +240,7 @@ For more detailed information, see the [indexing strategies page](https://docs.m
240240

241241
## Error Handling
242242

243-
If you need to filter certain errors from our driver we have a helpful tree of errors described in [docs/errors.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/errors.md).
243+
If you need to filter certain errors from our driver we have a helpful tree of errors described in [etc/notes/errors.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/errors.md).
244244

245245
It is our recommendation to use `instanceof` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code.
246246
We guarantee `instanceof` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.

‎docs/charts/README.md renamed to ‎etc/charts/README.md

File renamed without changes.

‎docs/charts/build_images.sh renamed to ‎etc/charts/build_images.sh

File renamed without changes.

‎docs/charts/imgs/MongoError.svg renamed to ‎etc/charts/imgs/MongoError.svg

File renamed without changes.

‎docs/charts/mermaid/MongoError.mmd renamed to ‎etc/charts/mermaid/MongoError.mmd

File renamed without changes.

‎etc/docs/README.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# docs_utils
2+
3+
This directory contains scripts to generate api docs as well our the Hugo site template used for the MongoDB node driver documentation.
4+
5+
There are two scripts contained in this folder.
6+
7+
- `legacy-generate.sh` was used to generate API documentation before the driver's docs
8+
were moved into the main repository. This script has the ability to generate api docs for older versions of the driver (in case it becomes
9+
necessary to backport a feature).
10+
11+
- `generate-docs.ts` is used to generate API docs for a major or minor release.
12+
13+
### Dependencies
14+
15+
`generate-docs.ts` requires the following in addition to dependencies installed with `npm i`:
16+
17+
* Hugo static web generator `v0.30.2`
18+
* You can download the right version [here](https://github.com/gohugoio/hugo/releases/tag/v0.30.2)
19+
* ts-node
20+
21+
Note: `typedoc` is also a dependency but it is downloaded by the docs generation script automatically.
22+
23+
`legacy-generate.sh` requires the following (in addition to Hugo):
24+
25+
* jsdoc v3
26+
* node (v6.x or v8.x) and npm (>= 3.x). Note: worked for me with 8.17.0, but not 8.0.0.
27+
* python sphinx
28+
29+
### Usage
30+
31+
To generate API documentation for a new major or minor version:
32+
33+
`npm run docs:build -- <version> <optional status for the version>`
34+
35+
The generated docs can be previewed using `npm run docs:preview`.
36+
37+
Once everything looks correct, open a PR against `main`. Our docs are hosted out of the `docs` folder on the
38+
main branch, and once the PR is merged Github will automatically update the hosted documentation.

‎etc/docs/generate-docs.ts

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
#! /usr/bin/env ts-node
2+
3+
import { parse, stringify } from '@iarna/toml';
4+
import { exec as execCb } from 'child_process';
5+
import { readFileSync, writeFile as writeFileCb } from 'fs';
6+
import { promisify } from 'util';
7+
import { createInterface } from 'readline';
8+
import { chdir } from 'process';
9+
10+
const exec = promisify(execCb);
11+
const writeFile = promisify(writeFileCb);
12+
13+
const RELEASES_TOML_FILE = './template/data/releases.toml';
14+
const RELEASES_JSON_FILE = './template/static/versions.json';
15+
16+
interface JsonVersionSchema {
17+
version: string;
18+
}
19+
20+
interface VersionSchema {
21+
version: string;
22+
status: string;
23+
api: string;
24+
usesMongoDBManual?: boolean;
25+
docs?: string;
26+
semverVersion: string;
27+
}
28+
29+
interface TomlVersionSchema {
30+
current: string;
31+
mongodDBManual: string;
32+
versions: VersionSchema[]
33+
}
34+
35+
function prompt(prompt: string) : Promise<string> {
36+
const rl = createInterface({
37+
input: process.stdin,
38+
output: process.stderr
39+
})
40+
41+
return new Promise((resolve, _) => {
42+
rl.question(prompt, (answer) => {
43+
rl.close();
44+
resolve(answer);
45+
})
46+
})
47+
}
48+
49+
function getCommandLineArguments() : { semverVersion: string, status: string } {
50+
const args = process.argv.slice(2);
51+
52+
if (args.length === 0) {
53+
console.error('usage: generate-docs.ts <semver version> <status (optional)>')
54+
process.exit(1);
55+
}
56+
57+
const semverVersion = args.shift();
58+
const status = args.shift() ?? 'current';
59+
return {
60+
semverVersion,
61+
status
62+
}
63+
}
64+
65+
async function copyNewDocsToGeneratedSite({ semverVersion }: VersionSchema) {
66+
const outputDirectory = `./temp/${semverVersion}`;
67+
const pathToBuiltDocs = './build';
68+
const command = `cp -R ${pathToBuiltDocs} ${outputDirectory}`;
69+
return await exec(command);
70+
}
71+
72+
async function updateSiteTemplateForNewVersion(newVersion: VersionSchema, tomlData: TomlVersionSchema, jsonVersions: JsonVersionSchema[]) {
73+
const versionExists = jsonVersions.some(({ version }) => version === newVersion.semverVersion);
74+
if (versionExists) {
75+
const existingVersionIndex = tomlData.versions.findIndex(({ semverVersion }) => semverVersion === newVersion.semverVersion);
76+
tomlData.versions[existingVersionIndex] = newVersion;
77+
} else {
78+
tomlData.versions.unshift(newVersion);
79+
tomlData.current = newVersion.version;
80+
81+
jsonVersions.unshift({ version: newVersion.semverVersion })
82+
}
83+
84+
await writeFile(RELEASES_TOML_FILE, stringify(tomlData as any));
85+
await writeFile(RELEASES_JSON_FILE, JSON.stringify(jsonVersions, null, 4));
86+
87+
// generate the site from the template
88+
await exec(`hugo -s template -d ../temp -b "/node-mongodb-native"`);
89+
}
90+
91+
async function main() {
92+
chdir(__dirname);
93+
94+
const { semverVersion, status } = getCommandLineArguments();
95+
96+
const newVersion: VersionSchema = {
97+
version: `${semverVersion} Driver`,
98+
status,
99+
api: `./${semverVersion}`,
100+
usesMongoDBManual: true,
101+
semverVersion
102+
};
103+
104+
const response = await prompt(`
105+
Generating docs for the following configuration.
106+
${JSON.stringify(newVersion, null, 2)}
107+
Does this look right? [y/n] `);
108+
109+
if (response.trim() !== 'y') {
110+
console.error("something went wrong. Exiting...");
111+
process.exit(1);
112+
}
113+
114+
console.error('Installing typedoc...');
115+
await exec('npm i --no-save typedoc');
116+
117+
console.error('Successfully installed typedoc. Building api docs for current branch...');
118+
119+
await exec('npm run build:typedoc');
120+
121+
console.error('Successfully built api docs for current branch');
122+
123+
console.error('Generating new doc site...')
124+
const tomlVersions = parse(readFileSync(RELEASES_TOML_FILE, { encoding: 'utf8' })) as unknown as TomlVersionSchema;
125+
const jsonVersions = JSON.parse(readFileSync(RELEASES_JSON_FILE, { encoding: 'utf8' })) as unknown as JsonVersionSchema[];
126+
127+
const versionAlreadyExists = jsonVersions.some(({version }) => version === semverVersion)
128+
129+
if (versionAlreadyExists) {
130+
const response = await prompt(`Version ${semverVersion} already exists. Do you want to override the existing docs? [y/n] `);
131+
if (response !== 'y') {
132+
console.error("something went wrong. Exiting...");
133+
process.exit(1);
134+
}
135+
}
136+
137+
await updateSiteTemplateForNewVersion(newVersion, tomlVersions, jsonVersions);
138+
139+
await copyNewDocsToGeneratedSite(newVersion);
140+
141+
// copy the generated site to the docs folder
142+
await exec(`cp -R temp/. ../../docs/.`);
143+
144+
// cleanup
145+
await exec('rm -rf temp');
146+
147+
console.error('Successfully generated api documentation and updated the doc site.')
148+
}
149+
150+
main();

‎etc/docs/legacy-generate.sh

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
#!/usr/bin/env bash
2+
3+
#
4+
# This is a script that was
5+
#
6+
7+
set -o errexit
8+
set -o xtrace
9+
10+
echo "Warning - this script has not yet been run in the node-mongodb-native repo"
11+
12+
export JSDOC=${JSDOC:-jsdoc}
13+
export HUGO=${HUGO:-hugo}
14+
# The list of branches to clone and generate docs for
15+
# All the existing docs versions will be left untouched
16+
if [ "$#" -eq 0 ]; then
17+
export BRANCHES=("main")
18+
else
19+
export BRANCHES=( "$@" )
20+
fi
21+
22+
# ensure hugo is installed
23+
if ! command -v "$HUGO" &> /dev/null; then
24+
echo "$HUGO could not be found"
25+
echo "download hugo here: https://github.com/gohugoio/hugo/releases/tag/v0.30.2 and install it somewhere in your PATH"
26+
exit 1
27+
fi
28+
29+
# ensure jsdoc is installed
30+
if ! command -v "$JSDOC" &> /dev/null; then
31+
echo "$JSDOC could not be found"
32+
echo "npm i -g jsdoc"
33+
exit 1
34+
fi
35+
36+
function generate_3x () {
37+
local branch=$1
38+
39+
echo "== Generating $branch docs"
40+
pushd "checkout/$branch"
41+
$HUGO -s docs/reference -d ../../public -b "/node-mongodb-native/$branch" -t mongodb
42+
$JSDOC -c conf.json -t docs/jsdoc-template/ -d ./public/api
43+
cp -R ./public/api/scripts ./public/.
44+
cp -R ./public/api/styles ./public/.
45+
popd
46+
}
47+
48+
function generate_4x () {
49+
local branch=$1
50+
51+
echo "== Generating $branch docs"
52+
pushd "checkout/$branch"
53+
npm run build:docs
54+
popd
55+
}
56+
57+
DRIVER_CLONE_URL="https://github.com/mongodb/node-mongodb-native.git"
58+
59+
echo "== Generating Main docs"
60+
rm -rf ./public
61+
62+
# Generate the base site
63+
# when a new version is added, it's necessary to re-run the template
64+
# generation to add links for the new version on the main documentation page
65+
$HUGO -s template/ -d ../public -b "/node-mongodb-native"
66+
67+
for branch in "${BRANCHES[@]}"; do
68+
69+
if [ -d "checkout/$branch" ]; then
70+
echo "checkout/$branch already exists, resetting"
71+
echo "double check there are no unexpected changes"
72+
git --git-dir "checkout/$branch/.git" clean -dfx
73+
git --git-dir "checkout/$branch/.git" fetch origin
74+
git --git-dir "checkout/$branch/.git" reset --hard "origin/$branch"
75+
else
76+
echo "cloning driver $branch to checkout/$branch"
77+
git clone --branch "$branch" --depth 1 "$DRIVER_CLONE_URL" "checkout/$branch"
78+
fi
79+
80+
pushd "checkout/$branch"
81+
npm install
82+
npm install mongodb-client-encryption
83+
npm install --no-save typedoc
84+
popd
85+
86+
MAJOR_VERSION=${branch:0:1}
87+
88+
case $MAJOR_VERSION in
89+
"3")
90+
generate_3x "$branch"
91+
cp -R "checkout/$branch/public" "./public/$branch"
92+
;;
93+
"4")
94+
generate_4x "$branch"
95+
cp -R "checkout/$branch/docs/public" "./public/$branch"
96+
;;
97+
98+
# if 'main' is specified as a branch, we're releasing a new version
99+
# TODO: figure out a way to pass in the version
100+
"m")
101+
echo "HEY YOU BETTER EDIT ME!!!"
102+
echo "YOU NEED TO MANUALLY SPECIFY THE BRANCH FOR NOW"
103+
echo "TODO"
104+
VERSION=4.4
105+
exit 1
106+
107+
cp checkout/main "checkout/$VERSION"
108+
generate_4x "$VERSION"
109+
cp -R "checkout/$VERSION/docs/public" "./public/$VERSION"
110+
;;
111+
*)
112+
echo "no support for $branch docs"
113+
exit 1
114+
;;
115+
esac
116+
done
117+
118+
echo "copying generated docs to the gh-pages branch"
119+
rm -rf ./gh-pages
120+
git clone --branch "gh-pages" --depth 1 "$DRIVER_CLONE_URL" "gh-pages"
121+
cp -R "public/." "gh-pages/."
122+
123+
echo "cleaning up temporary branches"
124+
rm -rf "$WORKING_DIR"/checkout
125+
126+
pushd "gh-pages"
127+
git add -A
128+
git status
129+
popd
130+
131+
echo -e "Inspect the changes above. If they look right to you run the following:\n\n"
132+
133+
cat << EOF
134+
cd gh-pages
135+
git commit -m "Updated documentation"
136+
git push origin gh-pages
137+
cd ..
138+
EOF

‎etc/docs/template/config.toml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
baseurl = "/mongo-nodejs-driver/"
2+
languageCode = "en-us"
3+
title = "MongoDB Node.js Driver"
4+
canonifyurls = false
5+
6+
githubRepo = "node-mongodb-native"
7+
8+
[params]
9+
referenceDocsUrl = "https://docs.mongodb.com/drivers/node"

0 commit comments

Comments
 (0)