Update documentation

The follow operations should be performed in master branch unless otherwise specified

Setup docs compiling environment

1. Make sure the following dependencies are installed:

   • Node: LTS version v12.16.3+
   • Rust: v1.46.0+

2. Install mdBook

   cargo install mdbook
   

3. Initialize docs compiling environment

   make doc-init
   

   You can use make doc-clean to cleanup files generated in this step. If you want to redo the initialization, please do a cleanup first

Update docs

1. Run docs dev server:

   make doc-dev
   

   and a open browser tab at http://localhost:3000

2. Make changes to Markdown files in docs directory, which will trigger the dev server to hot-reload the docs in the browser. This is a good way for to preview the changes. Please note that anything other than a symbolic link or a Markdown file in docs will be copied to docs_output/book/html by make doc-dev or mmake doc-build then be synced to docs_output/gh-pages by make doc-deploy with extraneous files removed. So if you want to add a file to gh-pages, add to docs first, otherwise that file will be deleted during the syncing

Notes:

• If you have changed the anchor types in protos or their configuration in tools/anchor-types-updater/manifests (previously in provendb-releases before moving to the new cluster), you need to regenerate the Anchor Types page at docs/concepts/anchor_types.md

  make doc-anchortypes
  

• If you have changed the Node SDK code, you need to regenerate the Node SDK reference at docs_output/gh-pages/node_sdk/reference

  make doc-node
  

• If you want to temporarily ignore a link when building the docs, you can add it to output.linkcheck.exclude in book.toml. Please remember to remove it after you have fixed your problem

Deploy updated docs

1. Make a production build of the docs:

   make doc-build
   

   this will generate the htmls in docs_output/book

2. Sync changes to the directory docs_output/gh-pages (the checkout of gh-pages branch) from docs_output/book/html:

   make doc-deploy
   

3. Go to the docs_output/gh-pages directory, review changes and perform a git commit on gh-pages branch:

   cd docs_output/gh-pages
   # review changes
   git status
   # commit
   git add .
   git commit -am "Some meaningful commit message"