Merge pull request #35 from qiboteam/Adding-docs

Adding docs
2024-03-01 22:52:10 +01:00
parent 8e28e44042 63c3a19fb4
commit 51d54a940c
18 changed files with 1435 additions and 96 deletions
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,38 @@
+name: docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [master]
+    tags:
+      - "*"
+
+jobs:
+  evaluate-label:
+    runs-on: ubuntu-latest
+    outputs:
+      label: ${{ steps.label_step.outputs.version}}
+    steps:
+      - name: checks for the label
+        id: label_step
+        run: |
+          if [[ "${{ github.ref  }}" == "refs/heads/master" ]]; then
+                echo "version=latest" >> $GITHUB_OUTPUT
+          fi
+          if [[ "${{ github.ref_type }}" == "branch" ]] && [[ "${{ github.ref  }}" != "refs/heads/master" ]]; then
+                exit 1
+          fi
+          if [[ "${{ github.ref_type }}" == "tag" ]]; then
+                echo "version=stable" >> $GITHUB_OUTPUT
+          fi
+
+  deploy-docs:
+    needs: [evaluate-label]
+    uses: qiboteam/workflows/.github/workflows/deploy-ghpages-latest-stable.yml@main
+    with:
+      python-version: "3.10"
+      package-manager: "poetry"
+      dependency-path: "**/poetry.lock"
+      trigger-label: "${{needs.evaluate-label.outputs.label}}"
+      project: qibotn
+      poetry-extras: --with docs
--- a/.github/workflows/rules.yml
+++ b/.github/workflows/rules.yml
@@ -12,7 +12,7 @@ on:

 jobs:
  check:
-    # job to check cuda availability
+    # job to check cuda availability for local gpu host runners
    runs-on: ubuntu-latest
    steps:
      - id: step1
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
--- a/doc/make.bat
+++ b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
--- a/doc/source/.gitignore
+++ b/doc/source/.gitignore
@@ -0,0 +1 @@
+api-reference/
--- a/doc/source/_static/css/style.css
+++ b/doc/source/_static/css/style.css
@@ -0,0 +1,7 @@
+.wy-side-nav-search {
+    background-color: #6400FF;
+}
+
+.wy-nav-top {
+    background-color: #6400FF;
+}
--- a/doc/source/_static/qibo_logo_dark.svg
+++ b/doc/source/_static/qibo_logo_dark.svg
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:osb="http://www.openswatchbook.org/uri/2009/osb"
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   id="svg8"
+   version="1.1"
+   viewBox="0 0 90 35"
+   height="35mm"
+   width="90mm"
+   sodipodi:docname="qibo_logo.svg"
+   inkscape:export-filename="/home/carrazza/repo/qiboteam/qibo/doc/source/logo.png"
+   inkscape:export-xdpi="261.92001"
+   inkscape:export-ydpi="261.92001"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1869"
+     inkscape:window-height="1025"
+     id="namedview13"
+     showgrid="false"
+     inkscape:zoom="2.8284271"
+     inkscape:cx="153.85323"
+     inkscape:cy="71.280204"
+     inkscape:window-x="51"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="flowRoot815" />
+  <defs
+     id="defs2">
+    <linearGradient
+       osb:paint="solid"
+       id="linearGradient2367">
+      <stop
+         id="stop2365"
+         offset="0"
+         style="stop-color:#000000;stop-opacity:1;" />
+    </linearGradient>
+  </defs>
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     transform="translate(0,-262)"
+     id="layer1">
+    <g
+       id="flowRoot815"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none"
+       transform="matrix(0.90659938,0,0,0.90659938,-216.91173,-176.98871)"
+       aria-label="QIBO">
+      <g
+         id="g1073"
+         inkscape:export-xdpi="261.92001"
+         inkscape:export-ydpi="261.92001"
+         transform="matrix(1.5046043,0,0,1.5046043,-145.46705,-253.28199)">
+        <g
+           id="flowRoot2371"
+           style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none"
+           transform="matrix(0.82282627,0,0,0.82282627,139.12023,451.94249)"
+           aria-label="QIBO">
+          <path
+             sodipodi:nodetypes="ccsssscscccscsccscsssc"
+             inkscape:connector-curvature="0"
+             id="path1057"
+             style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:40px;font-family:'URW Gothic L';-inkscape-font-specification:'URW Gothic L, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#000000"
+             d="m 221.43789,77.595414 c -1.82831,-0.788504 -32.12188,0.399305 -51.6517,-6.124563 2.4,-2.48 3.56,-5.56 3.56,-9.48 0,-8.84 -6.71135,-15.283251 -15.67135,-15.283251 -8.88,0 -15.76,6.68 -15.76,15.28 0,8.52 7.08,15.32 16,15.32 3,0 6.15135,-1.036749 8.23135,-2.476749 2.52,1.72 4.44,2.4 7,2.4 0.16,0 0.4,0 0.72,-0.04 z M 161.47484,71.2676 c -1.24,0.56 -2.08,0.76 -3.56,0.76 -3.72,0 -6.52,-1.36 -8.76,-4.32 1.28,-0.24 1.88,-0.32 2.84,-0.32 3.24,0 6.08,1.16 9.48,3.88 z m 3.92,-2.64 c -3.6,-3.56 -8.64,-5.72 -13.36,-5.72 -1.76,0 -3.2,0.16 -4.56,0.52 -0.08,-0.72 -0.08,-1.04 -0.08,-1.4 0,-5.72 4.4,-10.04 10.2,-10.04 5.84,0 10.2,4.36 10.2,10.24 0,2.68 -0.8,4.76 -2.4,6.4 z" />
+          <path
+             id="path1059"
+             style="font-weight:bold;font-size:28.37454605px;fill:#000000"
+             d="m 176.23806,76.7876 h 3.88732 V 55.81881 h -3.88732 z"
+             inkscape:connector-curvature="0" />
+          <path
+             id="path1061"
+             style="font-weight:bold;font-size:28.37454605px;fill:#000000"
+             d="m 184.16299,76.7876 h 5.58978 c 2.32671,0 4.02919,-0.36887 5.30604,-1.163357 1.73085,-1.049858 2.72396,-2.922578 2.72396,-5.079044 0,-1.305229 -0.36887,-2.582083 -1.02149,-3.43332 -0.59586,-0.794487 -1.19173,-1.191731 -2.5537,-1.759221 1.67409,-0.879611 2.32671,-1.986219 2.32671,-3.944062 0,-1.957844 -0.87961,-3.603568 -2.38346,-4.568302 -1.24848,-0.794488 -2.55371,-1.021484 -5.67491,-1.021484 h -4.31293 z m 3.88731,-3.717066 v -5.362789 h 1.84434 c 2.69559,0 3.97244,0.879611 3.97244,2.752331 0,1.815971 -1.16336,2.610458 -3.88731,2.610458 z m 0,-9.164978 v -4.284557 h 1.58897 c 2.0146,0 3.00771,0.680989 3.00771,2.128091 0,1.503851 -0.99311,2.156466 -3.3482,2.156466 z"
+             inkscape:connector-curvature="0" />
+          <path
+             id="path1063"
+             style="font-weight:bold;font-size:28.37454605px;fill:#000000"
+             d="m 210.61028,55.449941 c -6.2424,0 -11.06607,4.738549 -11.06607,10.867451 0,6.043778 4.88042,10.839077 11.0377,10.839077 6.10052,0 10.8107,-4.73855 10.8107,-10.867451 0,-5.98703 -4.7953,-10.839077 -10.78233,-10.839077 z m -0.0567,3.74544 c 3.88731,0 6.92339,3.1212 6.92339,7.150386 0,4.029185 -2.95095,7.065262 -6.92339,7.065262 -3.97244,0 -7.09364,-3.1212 -7.09364,-7.093637 0,-4.05756 3.06445,-7.122011 7.09364,-7.122011 z"
+             inkscape:connector-curvature="0" />
+        </g>
+        <rect
+           y="506.51813"
+           x="261.8475"
+           height="5.5406642"
+           width="10.228919"
+           id="rect957"
+           style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.10302305;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+        <rect
+           y="503.69379"
+           x="257.51999"
+           height="3.4096398"
+           width="6.7660036"
+           id="rect959"
+           style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.83806002;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      </g>
+    </g>
+  </g>
+</svg>
--- a/doc/source/_static/qibo_logo_light.svg
+++ b/doc/source/_static/qibo_logo_light.svg
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   id="svg8"
+   version="1.1"
+   viewBox="0 0 90 35"
+   height="35mm"
+   width="90mm"
+   sodipodi:docname="qibo_logo_light.svg"
+   inkscape:export-filename="/home/carrazza/repo/qiboteam/qibo/doc/source/logo.png"
+   inkscape:export-xdpi="261.92001"
+   inkscape:export-ydpi="261.92001"
+   inkscape:version="1.2.2 (732a01da63, 2022-12-09, custom)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="2497"
+     inkscape:window-height="1376"
+     id="namedview13"
+     showgrid="false"
+     inkscape:zoom="2.8284271"
+     inkscape:cx="153.9725"
+     inkscape:cy="71.594562"
+     inkscape:window-x="63"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="flowRoot815"
+     inkscape:showpageshadow="2"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm" />
+  <defs
+     id="defs2">
+    <linearGradient
+       id="linearGradient2367"
+       inkscape:swatch="solid">
+      <stop
+         id="stop2365"
+         offset="0"
+         style="stop-color:#000000;stop-opacity:1;" />
+    </linearGradient>
+  </defs>
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     transform="translate(0,-262)"
+     id="layer1">
+    <g
+       id="flowRoot815"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none"
+       transform="matrix(0.90659938,0,0,0.90659938,-216.91173,-176.98871)"
+       aria-label="QIBO">
+      <path
+         style="fill:#ffffff;fill-opacity:1;stroke:#ffffff;stroke-width:0;stroke-dasharray:none;stroke-opacity:1"
+         d="m 308.44186,522.48902 c -11.12297,-0.1006 -22.91662,-0.20496 -26.20811,-0.23192 -5.11415,-0.0419 -6.09708,-0.0743 -6.75839,-0.22296 -1.65231,-0.37139 -3.27213,-1.06624 -4.99681,-2.14345 -0.45812,-0.28614 -0.87938,-0.5201 -0.93613,-0.51991 -0.0568,2.1e-4 -0.47432,0.22157 -0.92794,0.49196 -4.10006,2.44398 -9.51715,3.13647 -14.46957,1.84972 -3.78898,-0.98446 -7.45414,-3.21039 -9.88651,-6.00428 -4.44138,-5.10151 -5.79461,-11.88933 -3.65283,-18.32271 1.31216,-3.94138 4.03608,-7.41622 7.60147,-9.69699 2.3024,-1.47284 5.08537,-2.48437 7.98661,-2.90289 1.27434,-0.18384 4.1649,-0.21017 5.45808,-0.0497 6.02561,0.7476 11.05859,3.87282 14.03264,8.71355 1.04539,1.70153 1.9443,4.04651 2.37536,6.19654 0.28447,1.41886 0.39493,4.77822 0.20756,6.3125 -0.41076,3.36356 -1.71376,6.37954 -3.72506,8.62211 -0.295,0.32892 -0.51913,0.61382 -0.49809,0.63313 0.22248,0.20409 7.4225,2.22543 7.92701,2.22543 0.0743,0 0.10783,-3.35341 0.10783,-10.78247 v -10.78247 h 2.37272 2.37272 l 0.0262,11.32242 0.0262,11.32243 0.36114,0.0635 c 0.19862,0.0349 1.22012,0.21062 2.26999,0.39041 1.04987,0.17979 2.01333,0.35021 2.14102,0.37872 l 0.23216,0.0518 v -11.77477 -11.77477 l 4.41101,0.0506 c 3.49847,0.0401 4.58991,0.0854 5.27576,0.2191 2.73116,0.5323 4.64501,2.25928 5.33567,4.81469 0.21115,0.78129 0.24064,2.66411 0.0538,3.43616 -0.28774,1.18904 -0.97993,2.11239 -2.16206,2.88408 l -0.55101,0.35969 1.0259,0.52697 c 1.57277,0.80787 2.43951,1.78326 2.95652,3.32714 0.91135,2.7214 0.32774,5.68806 -1.51151,7.68341 -0.48861,0.53008 -1.07391,0.95757 -1.98798,1.45198 -0.48752,0.26369 -0.56427,0.33543 -0.36113,0.33756 0.14187,10e-4 0.97764,0.0706 1.85726,0.15354 3.45188,0.32558 10.74734,0.78482 14.70338,0.92556 l 1.54772,0.0551 -0.72227,-0.16015 c -5.25686,-1.1656 -9.17072,-4.90745 -10.42813,-9.96981 -0.3265,-1.31451 -0.44765,-3.61658 -0.26,-4.94036 0.55545,-3.91841 2.62402,-7.21586 5.86551,-9.35006 2.26025,-1.48815 4.71811,-2.19764 7.61319,-2.19764 2.8838,0 5.17666,0.69545 7.57836,2.29861 0.98384,0.65673 2.78882,2.47361 3.45675,3.47956 1.99467,3.00408 2.74074,6.68281 2.06593,10.18681 -0.90486,4.6986 -4.23807,8.54925 -8.67877,10.02603 -1.02357,0.3404 -2.30536,0.62381 -2.90066,0.64137 l -0.39128,0.0115 0.46432,0.0814 c 0.25537,0.0448 2.39123,0.13741 4.74634,0.2059 11.359,0.33032 5.97987,0.35342 -22.44198,0.0964 z m 18.55282,-5.19771 c 1.61549,-0.47543 2.77679,-1.19752 3.93119,-2.44439 1.69733,-1.83327 2.54333,-4.87296 2.08541,-7.49293 -0.29775,-1.70355 -0.77722,-2.8281 -1.75162,-4.1082 -1.03007,-1.35325 -2.57186,-2.41215 -4.29671,-2.951 -0.68783,-0.21489 -0.96884,-0.24122 -2.52794,-0.23685 -1.6409,0.005 -1.81069,0.0237 -2.63114,0.29587 -1.11611,0.37027 -1.85195,0.74206 -2.6376,1.33264 -1.72349,1.29557 -2.88849,3.19575 -3.30029,5.38292 -0.20864,1.10815 -0.15413,3.04635 0.11318,4.02409 0.9121,3.33627 3.48829,5.72444 6.90812,6.40395 1.11107,0.22076 2.97469,0.12725 4.1074,-0.2061 z m -25.61859,-0.2885 c 1.72416,-0.43796 2.49515,-1.34936 2.50532,-2.96158 0.008,-1.29619 -0.30062,-2.01219 -1.14585,-2.65687 -0.82704,-0.6308 -1.55192,-0.78322 -3.96697,-0.83413 l -2.14101,-0.0451 v 3.37683 3.37681 l 2.08942,-0.0556 c 1.26752,-0.0337 2.31352,-0.11254 2.65909,-0.20032 z m -32.04295,-6.07848 c 1.43497,-1.83396 2.10338,-3.70909 2.27525,-6.3829 0.24364,-3.79045 -1.17566,-7.57044 -3.77497,-10.0538 -2.20298,-2.10472 -4.95571,-3.25776 -8.1895,-3.43034 -5.93089,-0.31652 -11.15657,3.21234 -12.78646,8.6346 -0.3865,1.28581 -0.51384,2.16538 -0.52286,3.61136 l -0.008,1.28977 3.97249,0.0626 c 3.03395,0.0478 4.20407,0.1035 4.95271,0.23576 4.6071,0.81394 8.92112,2.87977 12.28063,5.88073 0.53801,0.48059 1.03359,0.87719 1.10128,0.88133 0.0677,0.004 0.38245,-0.32396 0.69946,-0.7291 z m 30.60271,-5.18796 c 0.93298,-0.16645 1.50252,-0.43856 1.92498,-0.91972 0.82225,-0.93649 0.65628,-2.89684 -0.30538,-3.60709 -0.7275,-0.53729 -1.13803,-0.62621 -3.0964,-0.67068 l -1.83147,-0.0416 v 2.69274 2.69275 l 1.26397,-0.004 c 0.69518,-0.002 1.61512,-0.0662 2.0443,-0.14282 z"
+         id="path214" />
+    </g>
+  </g>
+</svg>
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -0,0 +1,114 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+from pathlib import Path
+
+from recommonmark.transform import AutoStructify
+from sphinx.ext import apidoc
+
+import qibotn
+
+# sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Qibotn"
+copyright = "The Qibo team"
+author = "The Qibo team"
+
+# The full version, including alpha/beta/rc tags
+release = qibotn.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+master_doc = "index"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "recommonmark",
+    "sphinxcontrib.katex",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_favicon = "favicon.ico"
+
+# custom title
+html_title = "QiboTN · v" + release
+
+html_static_path = ["_static"]
+html_show_sourcelink = False
+
+html_theme_options = {
+    "top_of_page_button": "edit",
+    "source_repository": "https://github.com/qiboteam/qibolab/",
+    "source_branch": "main",
+    "source_directory": "doc/source/",
+    "light_logo": "qibo_logo_dark.svg",
+    "dark_logo": "qibo_logo_light.svg",
+    "light_css_variables": {
+        "color-brand-primary": "#6400FF",
+        "color-brand-secondary": "#6400FF",
+        "color-brand-content": "#6400FF",
+    },
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/qiboteam/qibolab",
+            "html": """
+                    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                        <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                    </svg>
+                """,
+            "class": "",
+        },
+    ],
+}
+
+# Adapted this from
+# https://github.com/readthedocs/recommonmark/blob/ddd56e7717e9745f11300059e4268e204138a6b1/docs/conf.py
+# app setup hook
+
+autodoc_mock_imports = ["cupy", "cuquantum"]
+
+
+def run_apidoc(_):
+    """Extract autodoc directives from package structure."""
+    source = Path(__file__).parent
+    docs_dest = source / "api-reference"
+    package = source.parents[1] / "src" / "qibotn"
+    apidoc.main(["--no-toc", "--module-first", "-o", str(docs_dest), str(package)])
+
+
+def setup(app):
+    app.add_config_value("recommonmark_config", {"enable_eval_rst": True}, True)
+    app.add_transform(AutoStructify)
+    app.add_css_file("css/style.css")
+
+    app.connect("builder-inited", run_apidoc)
--- a/doc/source/favicon.ico
+++ b/doc/source/favicon.ico
--- a/doc/source/getting-started/index.rst
+++ b/doc/source/getting-started/index.rst
@@ -0,0 +1,11 @@
+Getting started
+===============
+
+In this section we present the basic aspects of the Qibotn design and provide installation instructions.
+Please visit the following sections to understand how ``qibotn`` works.
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    quickstart
--- a/doc/source/getting-started/installation.rst
+++ b/doc/source/getting-started/installation.rst
@@ -0,0 +1,10 @@
+Installation instructions
+=========================
+
+QiboTN can be installed directly from the source repository on Github:
+
+.. code-block::
+
+    git clone https://github.com/qiboteam/qibotn.git
+    cd qibotn
+    poetry install
--- a/doc/source/getting-started/quickstart.rst
+++ b/doc/source/getting-started/quickstart.rst
@@ -0,0 +1,52 @@
+Quick start
+===========
+
+Setting the backend
+"""""""""""""""""""
+QiboTN supports two backends cutensornet (using CuQuantum library) and Quimbbackend (using Quimb library) for tensor network based simulations. The backend can be set using the following command line.
+
+For CuQuantum library,
+
+.. testcode::
+   qibo.set_backend(backend="qibotn", platform="cutensornet", runcard=computation_settings)
+..
+
+and for Quimb library
+
+.. testcode::
+   qibo.set_backend(
+       backend="qibotn", platform="QuimbBackend", runcard=computation_settings
+   )
+..
+
+Setting the runcard
+"""""""""""""""""""
+Basic structure of runcard is
+
+.. testcode::
+   computation_settings = {
+       "MPI_enabled": False,
+       "MPS_enabled": False,
+       "NCCL_enabled": False,
+       "expectation_enabled": {
+           "pauli_string_pattern": "IXZ",
+       },
+   }
+..
+
+Basic example
+"""""""""""""
+
+.. testcode::
+   # Construct the circuit
+   c = Circuit(2)
+   # Add some gates
+   c.add(gates.H(0))
+   c.add(gates.H(1))
+
+   # Execute the circuit and obtain the final state
+   result = c()
+
+   print(result.state())
+
+..
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -0,0 +1,73 @@
+.. title::
+   QiboTN
+
+What is QiboTN?
+===============
+
+QiboTN  is the dedicated `Qibo <https://github.com/qiboteam/qibo>`_ backend to support large-scale simulation of quantum circuits and acceleration.
+
+Supported Computation:
+
+- Tensornet (TN)
+- Matrix Product States (MPS)
+
+Tensor Network contractions to:
+
+- dense vectors
+- expecation values of given Pauli string
+
+The supported HPC configurations are:
+
+- single-node CPU
+- single-node GPU or GPUs
+- multi-node multi-GPU with Message Passing Interface (MPI)
+- multi-node multi-GPU with NVIDIA Collective Communications Library (NCCL)
+
+Currently, the supported tensor network libraries are:
+
+- [cuQuantum](https://github.com/NVIDIA/cuQuantum), an NVIDIA SDK of optimized libraries and tools for accelerating quantum computing workflows.
+- [quimb](https://quimb.readthedocs.io/en/latest/), an easy but fast python library for ‘quantum information many-body’ calculations, focusing primarily on tensor networks.
+
+How to Use the Documentation
+============================
+
+Welcome to the comprehensive documentation for QiboTN! This guide will help you navigate through the various sections and make the most of the resources available.
+
+
+1. **Getting started**: Begin by referring to the
+   :doc:`/getting-started/installation/` guide to set up the ``QiboTN`` library in your environment.
+
+2. **Tutorials**: Explore the :doc:`getting-started/quickstart/` section for basic usage examples
+
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction
+
+   getting-started/index
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Main documentation
+
+    api-reference/modules
+    Developer guides <https://qibo.science/qibo/stable/developer-guides/index.html>
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Documentation links
+
+    Qibo docs <https://qibo.science/qibo/stable/>
+    Qibolab docs <https://qibo.science/qibolab/stable/>
+    Qibocal docs <https://qibo.science/qibocal/stable/>
+    Qibosoq docs <https://qibo.science/qibosoq/stable/>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- a/poetry.lock
+++ b/poetry.lock
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,20 @@ cuquantum-python-cu11 = { version = "^23.3.0", optional = true }
 [tool.poetry.extras]
 cuda = ["cupy", "cuquantum-python-cu11"]

+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+Sphinx = "^5.0.0"
+furo = "^2023.3.27"
+sphinxcontrib-bibtex = "^2.4.1"
+recommonmark = "^0.7.1"
+sphinx_markdown_tables = "^0.0.17"
+sphinx-copybutton = "^0.5.2"
+sphinxcontrib-katex = "^0.9.9"
+# to prevent Quimb warning
+kahypar = "^1.3.5"
+
 [tool.poetry.group.dev.dependencies]
 ipython = "^7.0.0"

@@ -50,6 +64,9 @@ pylint = "^3.0.3"
 test = "pytest"
 lint = "pylint src --errors-only"
 lint-warnings = "pylint src --exit-zero"
+docs = "make -C doc html"
+docs-clean = "make -C doc clean"
+test-docs = "make -C doc doctest"

 [tool.pylint.main]
 ignored-modules = ["cupy", "cuquantum", "mpi4py"]
--- a/src/qibotn/mps_contraction_helper.py
+++ b/src/qibotn/mps_contraction_helper.py
@@ -7,15 +7,16 @@ class MPSContractionHelper:
    """A helper class to compute various quantities for a given MPS.

    Interleaved format is used to construct the input args for `cuquantum.contract`.
-    A concrete example on how the modes are populated for a 7-site MPS is provided below:
+    A concrete example on how the modes are populated for a 7-site MPS is provided
+    below::

-          0     2     4     6     8    10     12    14
-    bra -----A-----B-----C-----D-----E-----F-----G-----
-             |     |     |     |     |     |     |
-            1|    3|    5|    7|    9|   11|   13|
-             |     |     |     |     |     |     |
-    ket -----a-----b-----c-----d-----e-----f-----g-----
-          15    16    17    18    19    20    21    22
+              0     2     4     6     8    10     12    14
+        bra -----A-----B-----C-----D-----E-----F-----G-----
+                 |     |     |     |     |     |     |
+                1|    3|    5|    7|    9|   11|   13|
+                 |     |     |     |     |     |     |
+        ket -----a-----b-----c-----d-----e-----f-----g-----
+              15    16    17    18    19    20    21    22


    The follwing compute quantities are supported:
--- a/src/qibotn/mps_utils.py
+++ b/src/qibotn/mps_utils.py
@@ -6,7 +6,7 @@ from cuquantum.cutensornet.experimental import contract_decompose


 def initial(num_qubits, dtype):
-    """Generate the MPS with an initial state of |00...00>"""
+    r"""Generate the MPS with an initial state of :math:`\ket{00...00}`"""
    state_tensor = cp.asarray([1, 0], dtype=dtype).reshape(1, 2, 1)
    mps_tensors = [state_tensor] * num_qubits
    return mps_tensors
@@ -19,7 +19,7 @@ def mps_site_right_swap(mps_tensors, i, **kwargs):
        "ipj,jqk->iqj,jpk",
        *mps_tensors[i : i + 2],
        algorithm=kwargs.get("algorithm", None),
-        options=kwargs.get("options", None)
+        options=kwargs.get("options", None),
    )
    mps_tensors[i : i + 2] = (a, b)
    return mps_tensors
@@ -64,7 +64,7 @@ def apply_gate(mps_tensors, gate, qubits, **kwargs):
                *mps_tensors[i : i + 2],
                gate,
                algorithm=kwargs.get("algorithm", None),
-                options=kwargs.get("options", None)
+                options=kwargs.get("options", None),
            )
            mps_tensors[i : i + 2] = (a, b)  # in-place update
        else: