How to Version Docs

Workflow

Before you proceed, make sure you have comit-js-sdk and comit.network repos in the same directory on your machine:

.
├──work/
|   ├── comit-js-sdk/ ~ tag 0.15.2
|   └── comit.network/
           └── docs/
                 └── comit-sdk/ # Generated Docs
           └── versioned_docs/  
                 └── version-0.15.2/    # Generated Folder
                         └── comit-sdk/ # Generated Docs

• Only modify files in docs/. You can create new .md files or modify existing files.
  • Avoid modifying versioned_docs/ directly.
  • Instead, use the yarn docusaurus docs:version command explained in Publishing as a New Version
• In comit.network/, regenerate SDK docs by running yarn build:sdk.
  • This command uses the comit-js-sdk repo version on your machine e.g. master or 0.15.2.
  • This command will automatically generate SDK docs of comit-js-sdk and update the website files.
• Commit and push your changes. Merge it.
  • Your changes won't be viewable in https://comit.network/docs/, but it will be in https://comit.network/docs/next/.

Publishing as a New Version

• To publish your changes to https://comit.network/docs/, run yarn docusaurus docs:version <your version e.g. 0.15.3>.
  • The above command will create a version-0.15.3 folder in versioned_docs/ and version-0.15.3-sidebars.json in versioned_sidebars. Think of these files as versioned snapshots of the documentation.
• Commit and push your changes. Merge.
  • Your changes will be published under https://comit.network/docs/
  • The website is automatically redeployed whenever master is updated.

Publishing as an Existing Version

You want to update the documentation for an existing version in versioned_docs/version-0.15.2.

• First, make sure you have the comit-js-sdk checked out to the existing version and not master.

.
├──work/
|   ├── comit-js-sdk/ ~ tag 0.15.2
|   └── comit.network/
           └── docs/
                 └── comit-sdk/ # Generated Docs
           └── versioned_docs/       
                 └── comit-sdk/ # Generated Docs

• In comit.network/, regenerate SDK docs by running yarn build:sdk.
  • This step ensures that the current comit-sdk/ in docs/ does not overwrite the folder in the existing version. Instead, we use the same comit-sdk/ version.
• Remove the version string (e.g. e.g. 0.15.2) you want to overwrite in versions.json.
• Then, run yarn docusaurus docs:version 0.15.2.