Merge pull request #289 from entropicalabs/update_documentation

Update of Readthedocs files
entropicalabs · Oct 27, 2023 · 8a317b8 · 8a317b8
2 parents ff7edb6 + 5a46df5
commit 8a317b8
Show file tree

Hide file tree

Showing 13 changed files with 273 additions and 341 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -12,3 +12,5 @@ amazon-braket-sdk==1.23.0
 autograd>=1.4
 semantic_version>=2.10
 autoray>=0.3.1
+myst_parser>=2.0.0
+# myst_nb
diff --git a/docs/source/changelog.md b/docs/source/changelog.md
@@ -0,0 +1,4 @@
+# CHANGELOG
+
+```{include} ../../CHANGELOG.md
+```
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -56,6 +56,8 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "nbsphinx",
     "sphinx.ext.intersphinx",
+    "myst_parser",
+    # "myst_nb",
 ]
 
 autodoc_mock_imports = [
@@ -124,3 +126,6 @@
 
 # def setup(app):
 #     app.connect(skip)
+
+# pygments_style = 'sphinx'
+# suppress_warnings = ["myst_header"]
diff --git a/docs/source/openqaoa_azure/openqaoa_azure_install.rst b/docs/source/openqaoa_azure/openqaoa_azure_install.rst
@@ -14,6 +14,6 @@ You can install the latest version of openqaoa-azure directly from PyPi. We reco
 
 Installation instructions for Developers
 ----------------------------------------
-OpenQAOA-Azure does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available [here]()
+OpenQAOA-Azure does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available :ref:`here <openqaoa>`
 
 Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/docs/source/openqaoa_braket/openqaoa_braket_install.rst b/docs/source/openqaoa_braket/openqaoa_braket_install.rst
@@ -3,7 +3,7 @@ OpenQAOA Braket Installation
 
 Install via PyPI
 ----------------
-You can install the latest version of openqaoa-braket directly from PyPi. We recommend creating a virtual environment with `python>=3.8` first and then simply pip install openqaoa-braket with the following command.
+You can install the latest version of openqaoa-braket directly from PyPi. We recommend creating a virtual environment with ``python>=3.8`` first and then simply pip install openqaoa-braket with the following command.
 
 **NOTE:** Installing ``openqaoa-braket`` installs ``openqaoa-core`` by default
 
@@ -14,6 +14,6 @@ You can install the latest version of openqaoa-braket directly from PyPi. We rec
 Installation instructions for Developers
 ----------------------------------------
 
-OpenQAOA-Braket does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available [here]()
+OpenQAOA-Braket does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available :ref:`here <openqaoa>`
 
 Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/docs/source/openqaoa_core/openqaoa_core_install.rst b/docs/source/openqaoa_core/openqaoa_core_install.rst
@@ -16,6 +16,6 @@ You can install the latest version of openqaoa-core directly from PyPi. We recom
 Installation instructions for Developers
 ----------------------------------------
 
-OpenQAOA-Core does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available [here]()
+OpenQAOA-Core does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available :ref:`here <openqaoa>`
 
 Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/docs/source/openqaoa_metapackage_install.rst b/docs/source/openqaoa_metapackage_install.rst
@@ -1,49 +1,64 @@
 OpenQAOA Metapackage Installation
 =================================
+.. _openqaoa:
 
 The following instructions install OpenQAOA along with all optional plugins
 
-OpenQAOA is divided into separately installable plugins based on the requirements of the user. The core elements of the package are placed in `openqaoa-core` which comes pre-installed with each flavour of OpenQAOA. 
+OpenQAOA is divided into separately installable plugins based on the requirements of the user. The core elements of the package are placed in ``openqaoa-core`` which comes pre-installed with each flavour of OpenQAOA. 
 
-Currently, OpenQAOA supports the following backends and each can be installed exclusively with the exception of `openqaoa-azure` which installs `openqaoa-qiskit` as an additional requirement because Azure backends support circuit submissions via `qiskit`.
-- `openqaoa-braket` for AWS Braket
-- `openqaoa-azure` for Microsoft Azure Quantum
-- `openqaoa-pyquil` for Rigetti Pyquil
-- `openqaoa-qiskit` for IBM Qiskit
+Currently, OpenQAOA supports the following backends and each can be installed exclusively with the exception of ``openqaoa-azure`` which installs ``openqaoa-qiskit`` as an additional requirement because Azure backends support circuit submissions via `qiskit`.
+
+- ``openqaoa-braket`` for AWS Braket
+- ``openqaoa-azure`` for Microsoft Azure Quantum
+- ``openqaoa-pyquil`` for Rigetti Pyquil
+- ``openqaoa-qiskit`` for IBM Qiskit
 
 The OpenQAOA metapackage allows you to install all OpenQAOA plug-ins together.
 
 Install via PyPI
 ----------------
 You can install the latest version of OpenQAOA directly from PyPI. First, create a virtual environment with python3.8, 3.9, 3.10 and then pip install openqaoa with the following command
-```
+.. code-block:: bash
+
 pip install openqaoa
-```
+
 
 Install via git clone
 ---------------------
 Alternatively, you can install OpenQAOA manually from the GitHub repository by following the instructions below. 
 
-**NOTE:** We recommend creating a python virtual environment for this project using a python environment manager, for instance Anaconda. Instructions can be found [here](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands). Make sure to use **python 3.8** (or newer) for the environment.
+**NOTE:** We recommend creating a python virtual environment for this project using a python environment manager, for instance Anaconda. Instructions can be found `here <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands>`_. Make sure to use **python 3.8** (or newer) for the environment.
+
 1. Clone the git repository:
-```
-git clone https://github.com/entropicalabs/openqaoa.git
-```
-2. After cloning the repository `cd openqaoa` and pip install the package with instructions from the Makefile as follows
-```
-make local-install
-```
+
+.. code-block:: bash
+ 
+    git clone https://github.com/entropicalabs/openqaoa.git
+
+
+2. After cloning the repository ``cd openqaoa`` and pip install the package with instructions from the Makefile as follows
+
+.. code-block:: bash
+
+    make local-install
+
 
 Installation instructions for Developers
 ----------------------------------------
-Users can install OpenQAOA in the developer mode via the Makefile. For a clean editable install of the package run the following command from the `openqaoa` folder.
-```
-make dev-install
-```
-The package can be installed as an editable with extra requirements defined in the `setup.py`. If you would like to install the extra requirements to be able run the tests module or generate the docs, you can run the following
+Users can install OpenQAOA in the developer mode via the Makefile. For a clean editable install of the package run the following command from the ``openqaoa`` folder.
+
+.. code-block:: bash
+
+    make dev-install
+
+
+The package can be installed as an editable with extra requirements defined in the ``setup.py``. If you would like to install the extra requirements to be able run the tests module or generate the docs, you can run the following
+
+.. code-block:: bash
+
+    make dev-install-x
+
 
-```
-make dev-install-x,   with x = {tests, docs, all}
-```
+with x = {tests, docs, all}
 
-Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
+Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/docs/source/openqaoa_pyquil/openqaoa_pyquil_install.rst b/docs/source/openqaoa_pyquil/openqaoa_pyquil_install.rst
@@ -4,7 +4,7 @@ OpenQAOA Pyquil Installation
 Install via PyPI
 ----------------
 
-You can install the latest version of openqaoa-pyquil directly from PyPi. We recommend creating a virtual environment with `python>=3.8` first and then simply pip install openqaoa-pyquil with the following command.
+You can install the latest version of openqaoa-pyquil directly from PyPi. We recommend creating a virtual environment with ``python>=3.8`` first and then simply pip install openqaoa-pyquil with the following command.
 
 **NOTE:** Installing ``openqaoa-pyquil`` installs ``openqaoa-core`` by default
 
@@ -15,6 +15,6 @@ You can install the latest version of openqaoa-pyquil directly from PyPi. We rec
 Installation instructions for Developers
 ----------------------------------------
 
-OpenQAOA-Qiskit does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available [here]()
+OpenQAOA-Qiskit does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available :ref:`here <openqaoa>`
 
 Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/docs/source/openqaoa_qiskit/openqaoa_qiskit_install.rst b/docs/source/openqaoa_qiskit/openqaoa_qiskit_install.rst
@@ -4,7 +4,7 @@ OpenQAOA Qiskit Installation
 Install via PyPI
 ----------------
 
-You can install the latest version of openqaoa-qiskit directly from PyPi. We recommend creating a virtual environment with `python>=3.8` first and then simply pip install openqaoa-qiskit with the following command.
+You can install the latest version of openqaoa-qiskit directly from PyPi. We recommend creating a virtual environment with ``python>=3.8`` first and then simply pip install openqaoa-qiskit with the following command.
 
 **NOTE:** Installing ``openqaoa-qiskit`` installs ``openqaoa-core`` by default
 
@@ -15,6 +15,6 @@ You can install the latest version of openqaoa-qiskit directly from PyPi. We rec
 Installation instructions for Developers
 ----------------------------------------
 
-OpenQAOA-Qiskit does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available [here]()
+OpenQAOA-Qiskit does not yet support developer install as a standalone package. If you wish to work in developer mode, please install the entire library. Instructions are available :ref:`here <openqaoa>`
 
 Should you face any issue during the installation, please drop us an email at [email protected] or open an issue!
diff --git a/examples/community_tutorials/04_binpacking.ipynb b/examples/community_tutorials/04_binpacking.ipynb
diff --git a/src/openqaoa-core/openqaoa/problems/tsp.py b/src/openqaoa-core/openqaoa/problems/tsp.py
@@ -179,7 +179,6 @@ def validate_graph(G):
         """
         # Set edge weights to be the distances between corresponding cities
         for u, v, weight in G.edges(data="weight"):
-            print(weight)
             if not isinstance(weight, float) and not isinstance(weight, int):
                 raise TypeError("The edge weights must be of type float or int")
 

diff --git a/src/openqaoa-core/requirements_docs.txt b/src/openqaoa-core/requirements_docs.txt
@@ -3,4 +3,5 @@ sphinx-autodoc-typehints>=1.18.1
 sphinx-rtd-theme>=1.0.0
 nbsphinx>=0.8.9
 ipython>=8.10.0
-nbconvert>=6.5.1
+nbconvert>=6.5.1
+myst_parser>=2.0.0