docs: updated readme (#29561)

docs/README.md

@@ -1,40 +1,63 @@
-# Docs Readme
+# Solana Docs Readme
 
-Solana's Docs are built using [Docusaurus 2](https://v2.docusaurus.io/) with `npm`.
+Solana's Docs are built using [Docusaurus v2](https://v2.docusaurus.io/) with `npm`.
 Static content delivery is handled using `vercel`.
 
-### Installing Docusaurus
+## Local Development
 
-```sh
-$ npm install
+To set up the Solana Docs site locally:
+
+- install dependencies using `npm`
+- build locally via `./build.sh`
+- run the local development server
+- make your changes and updates as needed
+
+> Note: After cloning this repo to your local machine, all the local development commands are run from within this `docs` directory.
+
+### Install dependencies
+
+Install the site's dependencies via `npm`:
+
+```bash
+npm install
 ```
 
-### Local Development
+### Build locally
 
-This command starts a local development server and opens up a browser window.
-Most changes are reflected live without having to restart the server.
-(You might have to run build.sh first if you run into failures)
+The build script generates static content into the `build` directory and can be served using any static content hosting service.
 
-```sh
-$ npm run start
+```bash
+./build.sh
 ```
 
-### Build Locally
+Running this build script requires **Docker**, and will auto fetch the [solanalabs/rust](https://hub.docker.com/r/solanalabs/rust) image from Docker hub to compile the desired version of the [Solana CLI](https://docs.solana.com/cli) from source.
 
-This command generates static content into the `build` directory and can be
-served using any static content hosting service.
+This build script will also:
 
-```sh
-$ docs/build.sh
+- generate the `cli/usage.md` document from the output of each of the Solana CLI commands and sub-commands
+- convert each of the `art/*.bob` files into SVG images used throughout the docs
+- generate the language [Translations](#translations)
+
+> Note: Running this build script is **required** before being able to run the site locally via the `npm run start` command since it will generate the `cli/usage.md` document.
+
+If you run into errors or issues with this step, see [Common Issues](#common-issues) below. See also [CI Build Flow](#ci-build-flow) for more details on production deployments of the docs.
+
+### Local development server
+
+This command starts the Docusaurus local development server and opens up a browser window.
+
+```bash
+npm run start
 ```
 
-### Translations
+> Note: Most changes are reflected live without having to restart the server or refresh the page. However, some changes may require a manual refresh of the page or a restart of the development server (via the command above).
 
-Translations are sourced from [Crowdin](https://docusaurus.io/docs/i18n/crowdin)
-and generated when master is built.
-For local development use the following two commands in the `docs` directory.
+## Translations
 
-To download the newest Documentation translations run:
+Translations are sourced from [Crowdin](https://docusaurus.io/docs/i18n/crowdin) and generated when `master` is built.
+For local development use the following two commands in this `docs` directory.
+
+To download the newest documentation translations run:
 
 ```sh
 npm run crowdin:download
@@ -46,14 +69,66 @@ To upload changes from `src` & generate [explicit IDs](https://docusaurus.io/doc
 npm run crowdin:upload
 ```
 
-### CI Build Flow
+## CI Build Flow
 
-The docs are built and published in Travis CI with the `docs/build.sh` script.
-On each PR, the docs are built, but not published.
+The docs are built and published in Travis CI with the `./build.sh` script. On each PR, the docs are built, but not published.
 
-In each post-commit build, docs are built and published using `vercel` to their
-respective domain depending on the build branch.
+In each post-commit build, docs are built and published using `vercel` to their respective domain depending on the build branch.
 
 - Master branch docs are published to `edge.docs.solana.com`
 - Beta branch docs are published to `beta.docs.solana.com`
 - Latest release tag docs are published to `docs.solana.com`
+
+## Common Issues
+
+### Bad sidebars file (or `cli/usage` not found)
+
+```bash
+Error: Bad sidebars file.
+These sidebar document ids do not exist:
+- cli/usage,
+```
+
+If you have NOT successfully run the build script, then the `cli/usage.md` file will not exist within your local repo (since it is in `.gitignore`). Not having this doc file, will result in the error message above.
+
+If the Rust toolchain (specifically `cargo`) is installed on your system, you can specifically build the `cli/usage.md` document via:
+
+```bash
+./build-cli-usage.sh
+```
+
+Or using Docker and the normal build script, you can perform a full production build of the docs to generate this file:
+
+```bash
+./build.sh
+```
+
+### Permission denied for the Docker socket
+
+```bash
+Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post
+```
+
+Running docs build script (`./build.sh`) required the use of Docker.\*\*\*\*
+
+Ensuring you have Docker installed on your system and it is running.
+
+You may also try running either of these build scripts (and by association, Docker) with elevation permissions via `sudo`:
+
+```bash
+sudo ./build.sh
+# or
+sudo ./build-cli-usage.sh
+```
+
+### Multiple SVG images not found
+
+```bash
+Error: Image static/img/***.svg used in src/***.md not found.
+```
+
+During the build process of the docs (specifically within the `./convert-ascii-to-svg.sh` script run by `./build.sh`), each of the `art/*.bob` files are converted to SVG images and saved to the `static/img` directory.
+
+To correct this issue, use the steps above to [build the docs locally](#build-locally).
+
+> Note: While not generating and saving these SVG images within your local repo will **NOT** prevent you from running the local development server, it will result in numerous output errors in your terminal.