Documentation on building doc locally (#11073)

* Adding documentation on building doc locally using tox, sphinx and make. * fix suggestions from ElePT * resetting Sphinx's cache. Co-authored-by: Eric Arellano <[email protected]> * Suggesting by Eric to open the html file Co-authored-by: Eric Arellano <[email protected]> * Update CONTRIBUTING.md * Leave tox as the only option --------- Co-authored-by: Elena Peña Tapia <[email protected]> Co-authored-by: Eric Arellano <[email protected]>
Qiskit · Dec 19, 2023 · f808fe5 · f808fe5
1 parent 43c6713
commit f808fe5
Showing 1 changed file with 17 additions and 1 deletion.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,6 +16,7 @@ community in this goal.
 * [Release notes](#release-notes)
 * [Testing](#testing)
 * [Style and Lint](#style-and-lint)
+* [Building API docs locally](#building-api-docs-locally)
 * [Development Cycle](#development-cycle)
   * [Branches](#branches)
   * [Release Cycle](#release-cycle)
@@ -388,7 +389,6 @@ like for the current state of the repo you can run: `tox -edocs` which will
 build all the documentation into `docs/_build/html` and the release notes in
 particular will be located at `docs/_build/html/release_notes.html`
 
-
 ## Testing
 
 Once you've made a code change, it is important to verify that your change
@@ -580,6 +580,22 @@ 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/#):
+
+```
+tox -edocs
+```
+
+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 Sphinx can get in a bad cache state. Run `tox -e docs-clean`
+to reset Sphinx's cache.
+
 ## Development cycle
 
 The development cycle for qiskit is all handled in the open using