Add troubleshooting section to docs-build dev docs (#12804) (#12805)

* Add troubleshooting section to docs-build dev docs

There are a couple of known failure modes for the documentation build
that require additional setup.  This documents these, to consolidate the
knowledge.

* Update CONTRIBUTING.md

Co-authored-by: Elena Peña Tapia <[email protected]>

---------

Co-authored-by: Elena Peña Tapia <[email protected]>
(cherry picked from commit a335504)

Co-authored-by: Jake Lishman <[email protected]>

CONTRIBUTING.md

@@ -17,6 +17,7 @@ community in this goal.
 * [Testing](#testing)
 * [Style and Lint](#style-and-lint)
 * [Building API docs locally](#building-api-docs-locally)
+  * [Troubleshooting docs builds](#troubleshooting-docs-builds)
 * [Development Cycle](#development-cycle)
   * [Branches](#branches)
   * [Release Cycle](#release-cycle)
@@ -639,21 +640,41 @@ rather than via `tox`. If you have installed the development packages in your py
 `pip install -r requirements-dev.txt`, then `ruff` and `black` will be available and can be run from
 the command line. See [`tox.ini`](tox.ini) for how `tox` invokes them.
 
+
 ## Building API docs locally
 
-If you have made changes to the API documentation, you can run the command below
-to build documentation locally to review the html output. 
-The easiest and recommended way to build the documentation is to use [**tox**](https://tox.readthedocs.io/en/latest/#):
+The API documentation is built with Sphinx.
+We recommend that you use [**tox**](https://tox.readthedocs.io/en/latest) to orchestrate this.
+Run a complete documentation build with
+```
+tox -e docs
+```
+
+The documentation output will be located at `docs/_build/html`.
+Open the `index.html` file there in your browser to find the main page.
+
+### Troubleshooting docs builds
 
+When you build documentation, you might get errors that look like
 ```
-tox -edocs
+ValueError: earliest-version set to unknown revision '1.0.0rc1'
 ```
+If so, you need to fetch Qiskit's `git` tags and stable branches, in order to fully build the release notes.
+To do this, run the command:
+```
+git fetch --tags upstream
+```
+where `upstream` is your name for the [git remote repository](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) that corresponds to https://github.com/Qiskit/qiskit (this repository).
+You might need to re-run this command if Qiskit has issued a new release since the last time you built the documentation.
 
-Once you run this command, the output will be located at `docs/_build/html`.
-Then, open up the file `index.html` in your browser.
+Sometimes, you might get errors about "names not existing" or "failed to import" during the docs build, even when the test suite passes.
+This can mean that Sphinx's cache has become invalidated, but hasn't been successfully cleared.
+Use the command:
+```
+tox -e docs-clean
+```
+to fully clean out all documentation build artefacts and partial builds, and see if the problem persists.
 
-Sometimes Sphinx can get in a bad cache state. Run `tox -e docs-clean`
-to reset Sphinx's cache.
 
 ## Development cycle