From 6a25c606118b26c0cf2774c8cac8095f156696e2 Mon Sep 17 00:00:00 2001 From: Roman Wixinger Date: Sun, 20 Oct 2024 10:53:52 +0200 Subject: [PATCH 1/2] =?UTF-8?q?[docs]=20Clarified=20usage=20of=20the=20edi?= =?UTF-8?q?table=20mode=20thanks=20to=20the=20valuable=20inpt=20by=20F?= =?UTF-8?q?=C3=A1bio=20Carneiro=20(fabiocfabini).=20Todo:=20Update=20docum?= =?UTF-8?q?entation=20on=20how=20to=20render=20the=20Sphinx=20docs=20local?= =?UTF-8?q?ly.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 54 +++++++++++++++++++++++++------------------ docs/source/index.rst | 31 ++++++++++++++++++++++--- 2 files changed, 60 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index d8de269..db6cfea 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,36 @@ The library is available on the Python Package Index (PyPI) with `pip install qu ### Installation as a contributor -For users who want to have control over the source code, we recommend the following installation. Clone the repository -from [Github](https://github.com/CERN-IT-INNOVATION/quantum-gates), create a new virtual environment, and activate the -environment. Then you can build the wheel and install it with the package manager of your choice as described in the -section [How to contribute](#how-to-contribute). This will install all dependencies in your virtual environment, -and install a working version of the library. +For users who want to have control over the source code, we recommend the following installation. + +1. Clone the repository: + +```bash +git clone https://github.com/CERN-IT-INNOVATION/quantum-gates.git +``` + +2. Navigate to the project directory: + +```bash +cd quantum_gates +``` + +3. Create virtual environment + +You can either use your IDE to set this up automatically or do it manually in the CLI. +```bash +python -m venv venv +source venv/bin/activate # On Windows use `venv\Scripts\activate` +``` +This saves your environment from pollution. + +4. Install the package in editable mode. + +```bash +pip install -e . +``` +This command installs the package in editable mode, allowing you to work directly with the source code. Any changes you +make will be immediately available without the need to reinstall the package. ## Quickstart @@ -119,11 +144,8 @@ plot_histogram(counts_ng, bar_labels=False, legend=['Noisy Gates simulation']) # Usage -We recommend to read the [overview](https://quantum-gates.readthedocs.io/en/latest/index.html) of the documentation as a 2-minute preparation. - - -## Imports -There are two ways of importing the package. 1) If you installed the code with pip, then the imports are simply of the form seen in the [Quickstart](<#quickstart>). +We recommend to read the [overview](https://quantum-gates.readthedocs.io/en/latest/index.html) of the documentation +as a 2-minute preparation. You can import the package modules as shown in the Quickstart: ```python from quantum_gates.simulators import MrAndersonSimulator @@ -132,18 +154,6 @@ from quantum_gates.circuits import EfficientCircuit from quantum_gates.utilities import DeviceParameters, setup_backend ``` -2) If you use the source code directly and develop within the repository, then the imports become - -```python -from src.quantum_gates._simulation.simulator import MrAndersonSimulator -from src.quantum_gates._gates.gates import standard_gates -from src.quantum_gates._simulation.circuit import EfficientCircuit -from src.quantum_gates._utility.device_parameters import ( - DeviceParameters, - setup_backend -) -``` - # Functionality The main components are the [gates](https://quantum-gates.readthedocs.io/en/latest/gates.html), diff --git a/docs/source/index.rst b/docs/source/index.rst index 3c37ff9..2ac2489 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -43,14 +43,39 @@ The library is available on the |pip_link| with ``pip install quantum-gates``. Installation as a contributor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For users who want to have access to the source code, we recommend cloning -the repository from |github_link|. +For users who want to contribute to the project or work with the latest source code, we recommend the following steps: + +1. Clone the Repository from |github_link|: + + .. code-block:: bash + + git clone https://github.com/CERN-IT-INNOVATION/quantum-gates.git + +2. Navigate to the project directory: + + .. code-block:: bash + + cd quantum-gates + +3. Create and activate a virtual environment + + .. code-block:: bash + + python -m venv venv + source venv/bin/activate # On Windows use `venv\Scripts\activate` + +4. Install the package in editable Mode: + + .. code-block:: bash + + pip install -e . + + Installing in editable mode allows you to work directly with the source code. Any changes you make will be reflected immediately without the need to reinstall the package. .. |github_link| raw:: html Github - Functionality -------------- From 7b871daed53f63593ac9bd85f147eb8a6ed679cf Mon Sep 17 00:00:00 2001 From: Roman Wixinger Date: Sun, 20 Oct 2024 11:03:25 +0200 Subject: [PATCH 2/2] [docs] Added instructions on how to build and view the documentation. --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index db6cfea..906e7e5 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,47 @@ Build the wheel with the command `python3 -m build --sdist --wheel .` and naviga Use `ls` to display the name of the wheel, and run `pip install .whl` with the correct filename. Now you can use your version of the library. +## Building the documentation + +The documentation for Noisy Quantum Gates is built using Sphinx and is hosted on +[ReadTheDocs](https://quantum-gates.readthedocs.io/en/latest/index.html). If you wish to build and view the +documentation locally, follow these steps: + +1. Navigate to the `docs` directory: + +From the root of the project, navigate to the `docs` folder: + +```bash +cd docs +``` + +2. Install the documentation requirements: + +```bash +pip install -r requirements.txt +``` +Note: It's recommended to perform this step in your virtual environment. + +3. Build the HTML documentation: + +Use the make command to build the HTML version of the documentation: + +```bash +make html +``` + +4. View and check the documentation locally + +Open the generated index.html file in your web browser to view the documentation: + +```bash +open build/html/index.html # On macOS +xdg-open build/html/index.html # On Linux +start build\html\index.html # On Windows (Command Prompt) +``` + +Or manually navigate to the build/html directory and open index.html with your preferred web browser. + # Credits Please cite the work using the following BibTex entry: