Add --skip-next-release option to yarn build

[parthpp]

Motivation

This patch resolves #1243. Docusaurus CLI command for building HTML files from MarkDown is docusaurus-build. After deploying the static website as a result of this build, the documentation for the next release can be accessed by visiting **/next*. This is ideal for open source projects because it enables transperancy and encourages contribution. However, a closed source project will appreciate an option to skip building and deploying the next version documents. The proposed feature adds an option to docusaurus-build command to skip the build for documents of the next release. Thus, when docusaurus-build --skip-next-release is executed, the resulting HTML files are only for the already released version.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

I have added test case for the build option. In addition to that, I have done some manual testing. Please follow the ReadMe file in this demo repository to try it yourself.

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 97c0b23

https://deploy-preview-1292--docusaurus-2.netlify.com

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit 97c0b23

https://deploy-preview-1292--docusaurus-preview.netlify.com

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[endiliey]

LGTM. LGTY @yangshun or @JoelMarcey ?

[yangshun]

I've hesitant to add even more features to v1 which we will have to port over to v2. @endiliey if you're ok with that decision, we can merge this.

[endiliey]

I've hesitant to add even more features to v1 which we will have to port over to v2

I don't mind merging this over and include it in the next minor release. However, @parthpp do you want to try help porting this over to our current WIP v2 ? Otherwise, this PR might have to wait.

Here are some pointers:

1. You need to modify the part where we parse all cli related commands
   https://github.com/facebook/Docusaurus/blob/1edbeecbe565cbbbc0a6e6532c7c2d0c58d78807/packages/docusaurus/bin/docusaurus.js#L41-L50

2. Need to modify this build cli function and the essential load part.
   https://github.com/facebook/Docusaurus/blob/1edbeecbe565cbbbc0a6e6532c7c2d0c58d78807/packages/docusaurus/lib/commands/build.js#L42-L46

It should be something like

module.exports = async function build(siteDir, cliOptions = {}) {
  const skipNextRelease = {cliOptions};
  const props = await load({siteDir, skipNextRelease}); 
  // .....

https://github.com/facebook/Docusaurus/blob/1edbeecbe565cbbbc0a6e6532c7c2d0c58d78807/packages/docusaurus/lib/load/index.js#L20

3. Modify the loadDocs part at
   https://github.com/facebook/Docusaurus/blob/1edbeecbe565cbbbc0a6e6532c7c2d0c58d78807/packages/docusaurus/lib/load/docs/index.js#L15

All the related docs metadata is defined here.
No need to worry of things like readMetadata that got called at many places. We don't do that in v2.

Nice to have a test on v2

[parthpp]

No need to worry of things like readMetadata that got called at many places. We don't do that in v2.

What is the general mechanism used in V2 for build in the absence of metadata? Do you use just data structures?

[endiliey]

@parthpp

hmmm, we provide ‘addRoute’ API thats somewhat similar to gatsby ‘createPages’ API. So even docusaurus plugins can generate page. Its possible in v2 to get a .JSON or even .csv or any input file and get a pages created.

it could be easier if u trace back the code. We might still change things out but either way, we plan to make it as flexible and modular as possible

[parthpp]

@endiliey I am trying to add this feature to V2 as well, but I could not get the information to run it locally. Since init.js is not implemented yet. How would you suggest to test and run v2 locally? I checked your comment on #789 but that link is broken.

[yangshun]

@parthpp You can go into website and just do npm start. I fixed the broken link in the issue.

[parthpp]

@yangshun @endiliey Since v2 is not available in npm registry, I created npm link to v2 dependencies in website/package.json, then I did npm install on all packages and then npm install on website. But when I try to execute npm run-script build in website to run build.js, I get the following error. Can you help me guide to the problem here?

Error: '@docusaurus/plugin-content-blog' plugin cannot be found.
    at pluginConfigs.map (/Users/blabla/sourceCode/Docusaurus/packages/docusaurus/lib/load/plugins.js:22:15)
    at Array.map (<anonymous>)
    at loadPlugins (/Users/blabla/sourceCode/Docusaurus/packages/docusaurus/lib/load/plugins.js:12:33)
    at load (/Users/blabla/sourceCode/Docusaurus/packages/docusaurus/lib/load/index.js:77:47)

As far as I understand this issue happens when we try to require(pluginPath) in plugin.js

[endiliey]

we just recently moved to monorepo.

have you used yarn workspaces before ? its a superior command to yarn link. it sort of made the “packages” available as npm module to you although its still unpublished as npm module.

so here’s what needs to be done. rebase to master and ‘yarn’ at root directory.

cd website and yarn start. But this ‘website’ doesnt have version.

try utilizing this https://github.com/facebook/Docusaurus/tree/master/packages/docusaurus/test/__fixtures__/versioned-site

[endiliey]

note that npm i wont work because yarn workspaces is yarn specific feature.

https://yarnpkg.com/lang/en/docs/workspaces/

Your dependencies can be linked together, which means that your workspaces can depend on one another while always using the most up-to-date code available. This is also a better mechanism than yarn link since it only affects your workspace tree rather than your whole system.

Edit: just find out that lerna bootstrap is another alternative if you are using npm instead of yarn
https://github.com/lerna/lerna/tree/master/commands/bootstrap#usage

[parthpp]

I have implemented --skip-next-release in docusaurus v2. Following are some of the points I would like to highlight

1. Build command in Docusaurus 2 looks a bit wired when using options. For eg. In order to Skip Image compression during build, the command to use is yarn build --skip-image-compression true. The value is mandatory with option --skip-image-compression, but I find that the value is redundant since the option name itself says that we intent to skip image compression. The same argument applies to --skip-next-release. Hence, I have not added value with this option.
2. build-files-test.js uses actual docusaurus website docs to perform testing. Thus, the performance of tests suffers. Why are we running these test against the actual website instead of another small test fixtures?
3. What would be the best way to deploy docusaurus v2 locally for testing purposes? If I am using apache server, do I have to do any specific configuration that is different from the one required for docusaurus v1?
4. The v2 version of this feature can be tested by using versioned-website from test fixtures. Since this website is a test fixture, it does not have package.json. Hence add the following package.json at packages/docusaurus/test/__fixtures__/versioned-site/

{
  "name": "docusaurus-2-versioned-website",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "eject": "docusaurus eject",
    "deploy": "docusaurus deploy"
  },
  "dependencies": {
    "@docusaurus/plugin-content-blog": "^1.0.0",
    "@docusaurus/plugin-content-pages": "^1.0.0",
    "classnames": "^2.2.6",
    "docusaurus-2": "^2.0.0",
    "react": "^16.8.4",
    "react-dom": "^16.8.4",
    "react-youtube": "^7.9.0"
  }
}

and add packages/docusaurus/test/__fixtures__/versioned-site/ to the workspace in root package.json.

cc: @endiliey

[endiliey]

thank you @parthpp. I will test it out and patch it later if needed.

[endiliey]

I wanted to patch it out but I can't seem to push to your branch 😢.

Nvm, we'll fix it in master instead. Thank you for this. Regarding your question

Build command in Docusaurus 2 looks a bit wired when using options. For eg. In order to Skip Image compression during build, the command to use is yarn build --skip-image-compression true. The value is mandatory with option --skip-image-compression, but I find that the value is redundant since the option name itself says that we intent to skip image compression. The same argument applies to --skip-next-release. Hence, I have not added value with this option.

This was a WIP command. We'll remove it hahaha. Don't take everything in v2 code as final, there is a lot of WIP internally.

build-files-test.js uses actual docusaurus website docs to perform testing. Thus, the performance of tests suffers. Why are we running these test against the actual website instead of another small test fixtures?

Good idea. I wasn't the one who created that v1 test. It was done way before I contributed. Now that you mention it, i think its a good idea to use fixtures just like in v2

What would be the best way to deploy docusaurus v2 locally for testing purposes? If I am using apache server, do I have to do any specific configuration that is different from the one required for docusaurus v1?

We still build static files, nothing need to be changed for server deploying from v1.