automating the docs

.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

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)])

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
 ==================

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"]