Skip to content

Commit

Permalink
Update tab syntax for sphinx-design (Qiskit/qiskit-metapackage#1567)
Browse files Browse the repository at this point in the history 
In Qiskit/qiskit-metapackage#1558 the sphinx plugin sphinx-panel was switched to sphinx-design to
enable building the documentation with sphinx >=5.0.0. However, while
the build succeeded there were warnings emitted about tabbed directive
which was only valid for sphinx-panel. This prevented any tabbed
sections in the documentation from being built as sphinx just ignored
it (this is why it's best practice to build with -W to make warnings
fatal because they're almost always pointing to broken docs). This
commit fixes this by migrating the directives to use the syntax from
sphinx-design so that we're building the tabs sections of the
documentation.

Fixes Qiskit/qiskit-metapackage#1566
  • Loading branch information
@mtreinish @SamD-1998
mtreinish authored and SamD-1998 committed Sep 7, 2023
1 parent 1a5d07e commit 53f4247
Show file tree
Hide file tree
Showing 2 changed files with 385 additions and 378 deletions.
134 changes: 69 additions & 65 deletions docs/contributing_to_qiskit.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -696,43 +696,45 @@ from system-wide packages. This way, we avoid inadvertently becoming dependent o
particular system configuration. For developers, this also makes it easy to maintain multiple
environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).

.. tabbed:: Python venv
.. tab-set::

All Python versions supported by Qiskit include built-in virtual environment module
`venv <https://docs.python.org/3/tutorial/venv.html>`__.
.. tab-item:: Python venv

Start by creating a new virtual environment with ``venv``. The resulting
environment will use the same version of Python that created it and will not inherit installed
system-wide packages by default. The specified folder will be created and is used to hold the environment's
installation. It can be placed anywhere. For more detail, see the official Python documentation,
`Creation of virtual environments <https://docs.python.org/3/library/venv.html>`__.
All Python versions supported by Qiskit include built-in virtual environment module
`venv <https://docs.python.org/3/tutorial/venv.html>`__.

.. code-block:: sh
Start by creating a new virtual environment with ``venv``. The resulting
environment will use the same version of Python that created it and will not inherit installed
system-wide packages by default. The specified folder will be created and is used to hold the environment's
installation. It can be placed anywhere. For more detail, see the official Python documentation,
`Creation of virtual environments <https://docs.python.org/3/library/venv.html>`__.

python3 -m venv ~/.venvs/qiskit-dev
.. code-block:: sh
Activate the environment by invoking the appropriate activation script for your system, which can
be found within the environment folder. For example, for bash/zsh:
python3 -m venv ~/.venvs/qiskit-dev
.. code-block:: sh
Activate the environment by invoking the appropriate activation script for your system, which can
be found within the environment folder. For example, for bash/zsh:

source ~/.venvs/qiskit-dev/bin/activate
.. code-block:: sh
Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections
can be located for your system.
source ~/.venvs/qiskit-dev/bin/activate
.. code-block:: sh
Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections
can be located for your system.

pip install -U pip
.. code-block:: sh
.. tabbed:: Conda
pip install -U pip
For Conda users, a new environment can be created as follows.
.. tab-item:: Conda

.. code-block:: sh
For Conda users, a new environment can be created as follows.

.. code-block:: sh
conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv
conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv
.. _install-qiskit-terra:
Expand Down Expand Up @@ -832,84 +834,86 @@ using. Since Aer is a compiled C++ program with a Python interface, there are
non-Python dependencies for building the Aer binary which can't be installed
universally depending on operating system.

.. tabbed:: Linux
.. tab-set::

.. tab-item:: Linux

3. Install compiler requirements.
3. Install compiler requirements.

Building Aer requires a C++ compiler and development headers.
Building Aer requires a C++ compiler and development headers.

If you're using Fedora or an equivalent Linux distribution,
install using:
If you're using Fedora or an equivalent Linux distribution,
install using:

.. code:: sh
.. code:: sh
dnf install @development-tools
dnf install @development-tools
For Ubuntu/Debian install it using:
For Ubuntu/Debian install it using:

.. code:: sh
.. code:: sh
apt-get install build-essential
apt-get install build-essential
4. Install OpenBLAS development headers.
4. Install OpenBLAS development headers.

If you're using Fedora or an equivalent Linux distribution,
install using:
If you're using Fedora or an equivalent Linux distribution,
install using:

.. code:: sh
.. code:: sh
dnf install openblas-devel
dnf install openblas-devel
For Ubuntu/Debian install it using:
For Ubuntu/Debian install it using:

.. code:: sh
.. code:: sh
apt-get install libopenblas-dev
apt-get install libopenblas-dev
.. tabbed:: macOS
.. tab-item:: macOS


3. Install dependencies.
3. Install dependencies.

To use the `Clang <https://clang.llvm.org/>`__ compiler on macOS, you need to install
an extra library for supporting `OpenMP <https://www.openmp.org/>`__. You can use `brew <https://brew.sh/>`__
to install this and other dependencies.
To use the `Clang <https://clang.llvm.org/>`__ compiler on macOS, you need to install
an extra library for supporting `OpenMP <https://www.openmp.org/>`__. You can use `brew <https://brew.sh/>`__
to install this and other dependencies.

.. code:: sh
.. code:: sh
brew install libomp
brew install libomp
4. Then install a BLAS implementation; `OpenBLAS <https://www.openblas.net/>`__
is the default choice.
4. Then install a BLAS implementation; `OpenBLAS <https://www.openblas.net/>`__
is the default choice.

.. code:: sh
.. code:: sh
brew install openblas
brew install openblas
Next, install ``Xcode Command Line Tools``.
Next, install ``Xcode Command Line Tools``.

.. code:: sh
.. code:: sh
xcode-select --install
xcode-select --install
.. tabbed:: Windows
.. tab-item:: Windows

On Windows you need to use `Anaconda3 <https://www.anaconda.com/distribution/#windows>`__
or `Miniconda3 <https://docs.conda.io/en/latest/miniconda.html>`__ to install all the
dependencies.
On Windows you need to use `Anaconda3 <https://www.anaconda.com/distribution/#windows>`__
or `Miniconda3 <https://docs.conda.io/en/latest/miniconda.html>`__ to install all the
dependencies.

3. Install compiler requirements.
3. Install compiler requirements.

.. code:: sh
.. code:: sh
conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime
conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime
4. Install binary and build dependencies.
4. Install binary and build dependencies.

.. code:: sh
.. code:: sh
conda install --update-deps -c conda-forge -y openblas cmake
conda install --update-deps -c conda-forge -y openblas cmake
5. Build and install qiskit-aer directly
Expand Down
Loading

0 comments on commit 53f4247

Please sign in to comment.