Get rid of jupyter-sphinx and sphinx-automodapi (#960)

* WIP: debug tutorials not rendering * Revert "WIP: debug tutorials not rendering" This reverts commit a991b42. * Get rid of jupyter-sphinx * Also get rid of automodapi
qiskit-community · Jul 6, 2023 · 7c16083 · 7c16083
1 parent 674074b
commit 7c16083
Show file tree

Hide file tree

Showing 7 changed files with 4 additions and 233 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -165,37 +165,13 @@ The actual docstring for the elements listed in the module docstring
 
 
     >  You can use any Sphinx directive or rst formatting in a docstring as it
-    >  makes sense. For example, one common extension used is the ``jupyter-execute``
-    >  directive, which is used to execute a code block in Jupyter and display both
-    >  the code and output. This is particularly useful for visualizations.
+    >  makes sense.
 
 ### Rebuilding Documentation
 
-If you make changes to the codebase and want to rebuild the documentation,
+If you make changes to the codebase and want to rebuild the documentation: `tox -e docs`.
 
-1. Install `sphinx` and `numpydoc`.
-```
-conda install sphinx numpydoc
-(or pip install -U sphinx)
-```
-
-2. Install [read the docs theme](https://github.com/Qiskit/qiskit_sphinx_theme) and set in the config `html_theme = "qiskit_sphinx_theme"`.
-```
-pip install qiskit_sphinx_theme
-```
-
-3. Install required packages.
-```
-pip install sphinx_automodapi
-pip install jupyter_sphinx
-```
-
-4. Make the docs.  In the `docs` directory,
-```
-make html
-```
-
-You can also use this to update the doc tree.
+Sometimes Sphinx can have bad cache state. Run `tox -e docs-clean` to reset Tox.
 
 ## Check-list for specific types of Pull Requests
 Please refer to [these instructions](https://github.com/Qiskit/qiskit-metal/blob/main/contributor_guidelines/pull_request_rules.md)
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/build_docs.py b/docs/build_docs.py
diff --git a/docs/conf.py b/docs/conf.py
@@ -129,7 +129,7 @@
 extensions = [
     'sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary',
     'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinx.ext.extlinks',
-    'jupyter_sphinx', 'nbsphinx',
+    "nbsphinx",
     "qiskit_sphinx_theme",
 ]
 

diff --git a/docs/contributor-guide.rst b/docs/contributor-guide.rst
@@ -476,12 +476,6 @@ The actual docstring for the elements listed in the module docstring
    The `napoleon documentation <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__
    contains a good example of how docstrings should be formatted.
 
-   .. note::metal
-      You can use any Sphinx directive or rst formatting in a docstring as it
-      makes sense. For example, one common extension used is the ``jupyter-execute``
-      directive, which is used to execute a code block in Jupyter and display both
-      the code and output. This is particularly useful for visualizations.
-
 Rebuilding Documentation
 ------------------------
 

diff --git a/docs/docstring_cheat_sheet.md b/docs/docstring_cheat_sheet.md
@@ -135,30 +135,6 @@ Embed source code without executing it
 <blank line>                # Blank line signifies end of source code
 ```
 
-### Python code that executes
-This embeds and display the source code, executes it, and displays the results
-
-```
-.. jupyter-execute::
-   <blank line>                          # Blank line required
-   from qiskit import QuantumCircuit
-   # Create a circuit with a register of three qubits
-   circ = QuantumCircuit(3)
-   # H gate on qubit 0, putting this qubit in a superposition of |0> + |1>.
-   circ.h(0)
-   # A CX (CNOT) gate on control qubit 0 and target qubit 1 generating a Bell state.
-   circ.cx(0, 1)
-   # CX (CNOT) gate on control qubit 0 and target qubit 2 resulting in a GHZ state.
-   circ.cx(0, 2)
-   # Draw the circuit
-   circ.draw()
-<blank line>                             # Blank line signifies end of source code
-```
-
-The code above with generate:
-
-![Missing code run image](https://github.com/Qiskit/qiskit-metal/blob/main/docs/images/coderun.jpg?raw=true "Code run")
-
 ### Ascii graphics (bulk verbatim)
 Dump many lines verbatim – many times used for ascii graphics
 

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -12,11 +12,8 @@ yapf==0.32.0
 # Doc Build
 sphinx~=7.0.1
 numpydoc==1.5.0
-sphinx-automodapi==0.14.1
-jupyter_sphinx==0.4.0
 nbsphinx==0.8.6
 qiskit-sphinx-theme~=1.12.0
-jupyter_nbgallery==2.0.0
 sphinx-intl~=2.1.0
 
 # Unit tests