From 8e89bb1ed86c5289b8c70e8e46316797a607b061 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Tue, 23 Jul 2024 15:14:19 +0000
Subject: [PATCH] Add troubleshooting section to docs-build dev docs (#12804)
 (#12805)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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 <57907331+ElePT@users.noreply.github.com>

---------

Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>
(cherry picked from commit a335504abd52f4f08183fb276c187951bc40385e)

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
---
 CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1ea3dc9f60f3..a5f1529d2bd3 100644
--- a/CONTRIBUTING.md
+++ b/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