diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000000..9fb026211a8 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,40 @@ +name: Documentation +on: + pull_request: + paths: + - '.github/workflows/documentation.yml' + - 'package.json' + - 'docs/**' + - 'lib' + - 'test' + - 'website.js' + - 'CHANGELOG.md' + push: + branches: + - master + paths: + - '.github/workflows/documentation.yml' + - 'package.json' + - 'docs/**' + - 'lib' + - 'test' + - 'website.js' + - 'CHANGELOG.md' +permissions: + contents: read + +jobs: + test-documentation: + runs-on: ubuntu-20.04 + name: Test Generating Docs + steps: + - uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3 + + - name: Setup node + uses: actions/setup-node@5b52f097d36d4b0b2f94ed6de710023fbb8b2236 # v3.1.0 + with: + node-version: 16 + + - run: npm install + - run: npm run docs:clean + - run: npm run docs:generate diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1566ea4e91..31b8fd2c3cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,11 +53,9 @@ To contribute to the [guide](http://mongoosejs.com/docs/guide.html) or [quick st If you'd like to preview your documentation changes, first commit your changes to your local master branch, then execute: * `npm install` -* `make docclean` -* `make gendocs` -* `node static.js` +* `npm run docs:view` -Visit `http://localhost:8089` and you should see the docs with your local changes. Make sure you `git reset --hard` before committing, because changes to `docs/*` should **not** be in PRs. +Visit `http://localhost:8089` and you should see the docs with your local changes. Make sure you `npm run docs:clean` before committing, because automated generated files to `docs/*` should **not** be in PRs. ### Plugins website diff --git a/Makefile b/Makefile deleted file mode 100644 index bfb73265772..00000000000 --- a/Makefile +++ /dev/null @@ -1,59 +0,0 @@ - -DOCS_ = $(shell find lib/ -name '*.js') -DOCS = $(DOCS_:.js=.json) -DOCFILE = docs/source/_docs -STABLE_BRANCH = master -LEGACY_BRANCH = 5.x - -test: - ./node_modules/.bin/mocha $(T) --async-only test/*.test.js - -docs: ghpages merge_stable docclean gendocs search -docs_legacy: legacy docclean_legacy gendocs copytmp ghpages copylegacy - -ghpages: - git checkout gh-pages - -search: - node docs/search.js - -gendocs: - node website.js - -site: - node website.js && node static.js - -merge_stable: - git merge $(STABLE_BRANCH) - -legacy: - git checkout $(LEGACY_BRANCH) - -docclean: - rm -f ./docs/*.{1,html,json} - rm -f ./docs/source/_docs - -docclean_legacy: - rm -rf ./docs/$(LEGACY_BRANCH)/* - rm -f ./docs/source/_docs - -copytmp: - mkdir -p ./tmp/docs/css - mkdir -p ./tmp/docs/js - mkdir -p ./tmp/docs/images - mkdir -p ./tmp/docs/api - mkdir -p ./tmp/docs/tutorials - mkdir -p ./tmp/docs/typescript - cp -R ./docs/*.html ./tmp/docs - cp -R ./docs/css/*.css ./tmp/docs/css - cp -R ./docs/js/*.js ./tmp/docs/js - cp -R ./docs/images/* ./tmp/docs/images - cp -R ./docs/api/* ./tmp/docs/api - cp -R ./docs/tutorials/* ./tmp/docs/tutorials - cp -R ./docs/typescript/* ./tmp/docs/typescript - cp index.html ./tmp - -copylegacy: - mkdir -p ./docs/$(LEGACY_BRANCH) - cp -R ./tmp/* ./docs/$(LEGACY_BRANCH)/ - rm -rf ./tmp diff --git a/package.json b/package.json index f4e64944b80..d6eae6c2ffc 100644 --- a/package.json +++ b/package.json @@ -50,9 +50,11 @@ "lodash.isequal": "4.5.0", "lodash.isequalwith": "4.4.0", "marked": "4.0.14", + "mkdirp": "^1.0.4", "mocha": "10.0.0", "moment": "2.x", "mongodb-memory-server": "8.5.2", + "ncp": "^2.0.0", "nyc": "15.1.0", "pug": "3.0.2", "q": "1.5.1", @@ -68,6 +70,21 @@ "lib": "./lib/mongoose" }, "scripts": { + "docs:clean": "npm run docs:clean:stable", + "docs:clean:stable": "rimraf index.html && rimraf -rf ./docs/*.html && rimraf -rf ./docs/api && rimraf -rf ./docs/tutorials/*.html && rimraf -rf ./docs/typescript/*.html && rimraf -rf ./docs/*.html && rimraf -rf ./docs/source/_docs && rimraf -rf ./tmp", + "docs:clean:legacy": "rimraf index.html && rimraf -rf ./docs/5.x && rimraf -rf ./docs/source/_docs && rimraf -rf ./tmp", + "docs:copy:tmp": "mkdirp ./tmp/docs/css && mkdirp ./tmp/docs/js && mkdirp ./tmp/docs/images && mkdirp ./tmp/docs/tutorials && mkdirp ./tmp/docs/typescript && ncp ./docs/css ./tmp/docs/css --filter=.css$ && ncp ./docs/js ./tmp/docs/js --filter=.js$ && ncp ./docs/images ./tmp/docs/images && ncp ./docs/tutorials ./tmp/docs/tutorials && ncp ./docs/typescript ./tmp/docs/typescript && cp index.html ./tmp", + "docs:copy:tmp:legacy": "rimraf ./docs/5.x && ncp ./tmp ./docs/5.x", + "docs:checkout:gh-pages": "git checkout gh-pages", + "docs:checkout:legacy": "git checkout 5.x", + "docs:generate": "node website.js", + "docs:generate:search": "node docs/search.js", + "docs:merge:stable": "git merge master", + "docs:merge:legacy": "git merge 5.x", + "docs:test": "npm run docs:generate && npm run docs:generate:search", + "docs:view": "node website.js && node static.js", + "docs:prepare:publish:stable": "npm run docs:checkout:gh-pages && docs:merge:stable && npm run docs:clean:stable && npm run docs:generate && npm run docs:generate:search", + "docs:prepare:publish:legacy": "npm run docs:checkout:legacy && docs:merge:legacy && npm run docs:clean:stable && npm run docs:generate && npm run docs:copy:tmp && docs:checkout:gh-pages && docs:copy:tmp:legacy", "lint": "eslint .", "lint-js": "eslint . --ext .js", "lint-ts": "eslint . --ext .ts", diff --git a/release-items.md b/release-items.md index fb321a58d84..9ceb5922cab 100644 --- a/release-items.md +++ b/release-items.md @@ -13,16 +13,16 @@ ## updating the website -For 5.x +For 6.x 0. Change to the master branch -1. execute `make docs` (when this process completes you'll be on the gh-pages branch) -2. `git commit -a -m 'chore: website 5.x.x'` +1. execute `npm run docs:prepare:publish:stable` (when this process completes you'll be on the gh-pages branch) +2. `git commit -a -m 'chore: website 6.x.x'` 3. `git push origin gh-pages` -For 4.x +For 5.x -0. Change to the 4.x branch +0. Change to the 5.x branch 1. execute `make docs_legacy` (when this process completes you'll be on the gh-pages branch) -2. `git commit -a -m 'chore: website 4.x.x'` +2. `git commit -a -m 'chore: website 5.x.x'` 3. `git push origin gh-pages`