From 405efcd4faa0f3ac5975f08c16a54b3d30271d46 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 21 Jan 2025 13:42:25 -0600 Subject: [PATCH] Clarify the notebook path (#2569) Address user feedback from Qiskit Slack --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- README.md | 4 +-- docs/guides/install-qiskit-source.mdx | 30 ++++++++--------- docs/guides/install-qiskit.mdx | 32 +++++++++++++------ .../qiskit-1.0-installation.mdx | 22 ++++++------- scripts/config/cspell/dictionaries/qiskit.txt | 1 + scripts/nb-tester/README.md | 2 +- 6 files changed, 52 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index f37e719bcda..7f618e5d0f2 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ graphviz`. ``` - To only execute specific notebooks, pass them as arguments. ```sh - tox -- path/to/notebook.ipynb path/to/another-notbook.ipynb + tox -- ``` - To write the execution results to the file, pass the `--write` argument. ```sh @@ -230,7 +230,7 @@ Some problems can be fixed automatically. To fix these problems, run: tox -e fix # Fix problems in a specific notebook -tox -e fix -- path/to/notebook +tox -e fix -- ``` If you use the Jupyter notebook editor, consider adding squeaky as a [pre-save diff --git a/docs/guides/install-qiskit-source.mdx b/docs/guides/install-qiskit-source.mdx index ff5bf4ac9cf..890ee09926c 100644 --- a/docs/guides/install-qiskit-source.mdx +++ b/docs/guides/install-qiskit-source.mdx @@ -5,28 +5,28 @@ description: Learn how to install the development version of Qiskit. --- # Install the Qiskit SDK and Qiskit Runtime from source -Installing the Qiskit SDK from source allows you to access the current development version, instead of using the version in the Python Package Index (PyPI) repository. This lets you inspect and extend the latest version of the Qiskit code more efficiently. +Installing the Qiskit SDK from source allows you to access the current development version, instead of using the version in the Python Package Index (PyPI) repository. This lets you inspect and extend the latest version of the Qiskit code more efficiently. ## Create and activate a new virtual environment -1. Create a minimal environment with only Python installed in it. +1. Navigate to your project directory and create a minimal environment with only Python installed in it. ```shell - python3 -m venv /path/to/virtual/environment + python3 -m venv .venv ``` ```shell - python3 -m venv /path/to/virtual/environment + python3 -m venv .venv ``` ```text - python3 -m venv c:\path\to\virtual\environment + python -m venv .venv ``` @@ -36,26 +36,26 @@ Installing the Qiskit SDK from source allows you to access the current developme ```shell - source /path/to/virtual/environment/bin/activate + source .venv/bin/activate ``` ```shell - source /path/to/virtual/environment/bin/activate + source .venv/bin/activate ``` ```text - c:\path\to\virtual\environment\Scripts\Activate.ps1 + .venv\Scripts\Activate.ps1 ``` ## Install the Rust compiler -A Rust compiler must be installed on your system to compile Qiskit. To install the Rust compiler, use the cross-platform Rust installer [rustup](https://rustup.rs/) or [another install method.](https://forge.rust-lang.org/infra/other-installation-methods.html) +A Rust compiler must be installed on your system to compile Qiskit. To install the Rust compiler, use the cross-platform Rust installer [rustup](https://rustup.rs/) or [another install method.](https://forge.rust-lang.org/infra/other-installation-methods.html) ## Install Qiskit @@ -67,7 +67,7 @@ Follow these steps to install Qiskit: git clone https://github.com/Qiskit/qiskit.git ``` -2. Change to the `qiskit` directory. +2. Change to the `qiskit` directory. ```bash cd qiskit @@ -79,9 +79,9 @@ cd qiskit pip install -r requirements-dev.txt ``` -4. Install `qiskit`. +4. Install `qiskit`. - * **Standard install**: + * **Standard install**: ```bash pip install . @@ -113,7 +113,7 @@ Follow these steps if you want to install Qiskit Runtime: git clone https://github.com/Qiskit/qiskit-ibm-runtime.git ``` -2. Change to the `qiskit-ibm-runtime` directory. +2. Change to the `qiskit-ibm-runtime` directory. ```bash cd qiskit-ibm-runtime @@ -127,7 +127,7 @@ pip install -r requirements-dev.txt 4. Install `qiskit-runtime`. We recommend using a [virtual environment](https://docs.python.org/3/library/venv.html) to avoid polluting your global Python installation. - * **Standard install**: + * **Standard install**: ```bash pip install . @@ -139,7 +139,7 @@ pip install -r requirements-dev.txt pip install -e . ``` - In editable mode, the compiled extensions are built in _debug mode_ without optimizations. + In editable mode, the compiled extensions are built in _debug mode_ without optimizations. ## Next steps diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 8ad6b591521..3cf780607fb 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -45,27 +45,27 @@ Whether you will work locally or in a cloud environment, the first step for all One important advantage of a virtual environment is that if your Python environment becomes corrupted somewhere along the way, you can easily delete the virtual environment and start over! - Choose a preferred location in which to store information about your virtual environments. Commonly they're stored in a directory named `.venv` within a user's home directory. + Choose a preferred location in which to store information about your virtual environments. Typically they're stored in a directory named `.venv` within each project directory you're working in. - First, create a minimal environment with only Python installed in it. + First, navigate to your project directory and create a minimal environment with only Python installed in it. ```shell - python3 -m venv /path/to/virtual/environment + python3 -m venv .venv ``` ```shell - python3 -m venv /path/to/virtual/environment + python3 -m venv .venv ``` ```text - python3 -m venv c:\path\to\virtual\environment + python -m venv .venv ``` @@ -75,19 +75,31 @@ Whether you will work locally or in a cloud environment, the first step for all ```shell - source /path/to/virtual/environment/bin/activate + source .venv/bin/activate ``` ```shell - source /path/to/virtual/environment/bin/activate + source .venv/bin/activate ``` + If using PowerShell: + + ```text + .venv\Scripts\Activate.ps1 + ``` + If using Git Bash: + + ```text + source .venv/scripts/activate + ``` + If using command prompt: + ```text - c:\path\to\virtual\environment\Scripts\Activate.ps1 + .venv\Scripts\activate ``` @@ -122,7 +134,7 @@ Whether you will work locally or in a cloud environment, the first step for all -1. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you will need to install Jupyter in your environment. +1. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you need to install Jupyter in your environment. ```shell pip install jupyter @@ -130,7 +142,7 @@ Whether you will work locally or in a cloud environment, the first step for all Then open your notebook as follows: ```shell - jupyter notebook path/to/notebook.ipynb + jupyter notebook ``` If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM QPUs, next [select an access channel](setup-channel) and finish your setup. diff --git a/docs/migration-guides/qiskit-1.0-installation.mdx b/docs/migration-guides/qiskit-1.0-installation.mdx index fc9f2234b05..1f74227d2f7 100644 --- a/docs/migration-guides/qiskit-1.0-installation.mdx +++ b/docs/migration-guides/qiskit-1.0-installation.mdx @@ -38,24 +38,24 @@ PowerShell is used for Windows commands. ### Create the new environment -1. Create a new virtual environment, using your preferred version of Python 3.8 or later. Use any path you choose in place of `/path/to/qiskit-1.0-venv`. +1. Create a new virtual environment in each project directory you're working in, using your preferred version of Python 3.8 or later. ```bash - python3 -m venv /path/to/qiskit-1.0-venv + python3 -m venv .venv ``` ```bash - python3 -m venv /path/to/qiskit-1.0-venv + python3 -m venv .venv ``` ```powershell - python3 -m venv C:\path\to\qiskit-1.0-venv + python -m venv .venv ``` @@ -66,19 +66,19 @@ PowerShell is used for Windows commands. ```bash - source /path/to/qiskit-1.0-venv/bin/activate + source .venv/bin/activate ``` ```bash - source /path/to/qiskit-1.0-venv/bin/activate + source .venv/bin/activate ``` ```powershell - C:\path\to\qiskit-1.0-venv\Scripts\activate.ps1 + .venv\Scripts\activate.ps1 ``` @@ -126,24 +126,24 @@ PowerShell is used for Windows commands. ### Use the new environment -Each time you start a new command line session, you must "activate" the environment by running the `activate` command: +Each time you start a new command line session, you must navigate to your project directory and "activate" the environment by running the `activate` command: ```bash - source /path/to/qiskit-1.0-venv/bin/activate + source .venv/bin/activate ``` ```bash - source /path/to/qiskit-1.0-venv/bin/activate + source .venv/bin/activate ``` ```powershell - C:\path\to\qiskit-1.0-venv\Scripts\activate.ps1 + .venv\Scripts\activate.ps1 ``` diff --git a/scripts/config/cspell/dictionaries/qiskit.txt b/scripts/config/cspell/dictionaries/qiskit.txt index 86093919732..3daf2bcd039 100644 --- a/scripts/config/cspell/dictionaries/qiskit.txt +++ b/scripts/config/cspell/dictionaries/qiskit.txt @@ -37,6 +37,7 @@ Hadamard Hamiltonians IBMQPU ITTL +ipynb Ipython MCMT MCMTV diff --git a/scripts/nb-tester/README.md b/scripts/nb-tester/README.md index 9d4764ac509..8622c57fc24 100644 --- a/scripts/nb-tester/README.md +++ b/scripts/nb-tester/README.md @@ -29,7 +29,7 @@ To use this tool, just run the `test-docs-notebooks` command, followed by a list of notebooks you'd like to execute. ``` -test-docs-notebooks path/to/notebook.ipynb path/to/another.ipynb +test-docs-notebooks ``` * To write the executed notebooks to disk, include the `--write` argument.