Merge pull request #27 from CERN-IT-INNOVATION/feature/docs

Feature/docs

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), 
@@ -184,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 <filename>.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:

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
 
    <a href="https://github.com/CERN-IT-INNOVATION/quantum-gates" target="_blank">Github</a>
 
-
 Functionality
 --------------