From 72223c66abede067a6dfbc4431e75d37079e2caf Mon Sep 17 00:00:00 2001
From: vinitha-balachandran
 <balachan@x1000c1s4b0n0.hostmgmt2000.cm.asp2a.nscc.sg>
Date: Fri, 1 Mar 2024 15:51:03 +0800
Subject: [PATCH] automating the docs

---
 .github/workflows/rules.yml | 20 ++++++++++++++++----
 docs/source/conf.py         | 20 +++++++++++++++++---
 docs/source/index.rst       |  8 +++++++-
 pyproject.toml              | 14 ++++++++++++++
 4 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/rules.yml b/.github/workflows/rules.yml
index 4ad1427..3e13faa 100644
--- 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
@@ -24,8 +24,6 @@ jobs:
 
   build:
     # job to build
-    needs: check
-    if: ${{fromJSON(needs.check.outputs.cuda_avail)}}
     strategy:
           matrix:
             os: [ubuntu-latest]
@@ -34,5 +32,19 @@ jobs:
     with:
       os: ${{ matrix.os }}
       python-version: ${{ matrix.python-version }}
-      poetry-extras: "--with analysis,tests"
+      poetry-extras: "--with docs"
     secrets: inherit
+#local_build
+   # job to build
+   #needs: check
+   #if: ${{fromJSON(needs.check.outputs.cuda_avail)}}
+   #strategy:
+    #matrix:
+      #os: [ubuntu-latest]
+      #python-version: [3.8, 3.9, "3.10", "3.11"]
+#uses: qiboteam/workflows/.github/workflows/rules-poetry.yml@main
+#with:
+#os: ${{ matrix.os }}
+#python-version: ${{ matrix.python-version }}
+#poetry-extras: "--with analysis,tests, docs"
+#secrets: inherit
diff --git a/docs/source/conf.py b/docs/source/conf.py
index e605977..ec0f9a9 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -9,13 +9,15 @@
 # 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.
 #
-import os
-import sys
+from pathlib import Path
 
-sys.path.insert(0, os.path.abspath(".."))
+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
 
@@ -56,3 +58,15 @@ exclude_patterns = []
 
 html_theme = "furo"
 html_static_path = ["_static"]
+
+# Adapted this from
+# https://github.com/readthedocs/recommonmark/blob/ddd56e7717e9745f11300059e4268e204138a6b1/docs/conf.py
+# app setup hook
+
+
+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)])
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 2539a33..1b9b97f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -48,10 +48,16 @@ Contents
 --------
 
 .. toctree::
-
+   :maxdepth: 2
+   :caption: Introduction
    usage
    api
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Main documentation
+
+    api-reference/modules
 
 Indices and tables
 ==================
diff --git a/pyproject.toml b/pyproject.toml
index 5a25924..5988502 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,17 @@ 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"
+
 [tool.poetry.group.dev.dependencies]
 ipython = "^7.0.0"
 
@@ -50,6 +61,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"]