Update user guide and documentation for v1.1.0

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Publish Sphinx Documentation
+
+on:
+  push:
+    branches:
+      - haoti/doc_update
+
+jobs:
+  publish_sphinx_docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.5.1"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install dependencies
+        working-directory: docs
+        run: |
+          uv sync --python 3.10
+          sudo apt-get update && sudo apt-get install -y doxygen graphviz
+      - name: Build api documentation
+        working-directory: docs
+        run: |
+          uv run bash api_doc_script.sh
+      - name: Sphinx build
+        working-directory: docs
+        run: |
+          uv run just doc
+      - name: Create index.html
+        working-directory: docs
+        run: |
+          uv run python redirect.py ${{ github.ref_name }} > build/index.html
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          personal_token: ${{ secrets.PAGES_PAT }}
+          external_repository: Cytnx-dev/Cytnx_doc
+          publish_dir: docs/build/
+          force_orphan: true

DoxygenLayout.xml

@@ -37,7 +37,7 @@
     </tab>
     <tab type="examples" visible="yes" title="" intro=""/>
     <tab type="user" visible="yes" title="version log" url="@ref version_log"/>
-    <tab type="user" visible="yes" title="User Guide" url="https://kaihsinwu.gitlab.io/Cytnx_doc"/>
+    <tab type="user" visible="yes" title="User Guide" url="../build/html/index.html"/>
   </navindex>
 
   <!-- Layout definition for a class page -->

Readme.md

@@ -22,14 +22,14 @@ Cytnx is a tensor network library designed for quantum physics simulations using
  **See also**
 [Release Note](misc_doc/version.log).
 
-## API Documentation:
-
-[https://kaihsinwu.gitlab.io/cytnx_api/](https://kaihsinwu.gitlab.io/cytnx_api/)
 
 ## User Guide [under construction]:
 
-[Cytnx User Guide](https://kaihsinwu.gitlab.io/Cytnx_doc/)
+[Cytnx User Guide](https://cytnx-dev.github.io/Cytnx_doc)
+
+## API Documentation:
 
+[API Documentation](https://cytnx-dev.github.io/Cytnx_doc/api_build/html)
 
 
 ## Objects:
@@ -243,25 +243,25 @@ You can contact us by:
 * Email, see below
 
 ## Developers & Maintainers
-Creator and Project manager | Affiliation     | Email
-----------------------------|-----------------|---------
-Kai-Hsin Wu                 |Boston Univ., USA|kaihsinwu@gmail.com
+Creator     | Affiliation        | Email
+------------|--------------------|--------------------
+Kai-Hsin Wu | QuEra, Boston, USA | kaihsinwu@gmail.com
 
 Developers      | Affiliation     | Roles
 ----------------|-----------------|---------
-Chang-Teng Lin  |NTU, Taiwan      |major maintainer and developer
-Ke Hsu          |NTU, Taiwan      |major maintainer and developer
-Ivana Gyro      |NTU, Taiwan      |major maintainer and developer
-Hao-Ti Hung     |NTU, Taiwan      |documentation and linalg
-Ying-Jer Kao    |NTU, Taiwan      |setuptool, cmake
+Chang-Teng Lin  | NTU, Taiwan     | major maintainer and developer
+Ke Hsu          | NTU, Taiwan     | major maintainer and developer
+Ivana Gyro      | NTU, Taiwan     | major maintainer and developer
+Hao-Ti Hung     | NTU, Taiwan     | documentation and linalg
+Manuel Schneider| NYCU, Taiwan    | developer, fermions, documentation
+Ying-Jer Kao    | NTU, Taiwan     | project manager, setuptool, cmake
 
 ## Contributors
 Contributors    | Affiliation
 ----------------|-----------------
 PoChung Chen    | NTHU, Taiwan
 Chia-Min Chung  | NSYSU, Taiwan
 Ian McCulloch   | NTHU, Taiwan
-Manuel Schneider| NYCU, Taiwan
 Yen-Hsin Wu     | NTU, Taiwan
 Po-Kwan Wu      | OSU, USA
 Wen-Han Kao     | UMN, USA
@@ -271,10 +271,10 @@ Yu-Cheng Lin    | NTU, Taiwan
 
 ## References
 * Paper:
-[https://arxiv.org/abs/2401.01921](https://arxiv.org/abs/2401.01921)
+https://scipost.org/10.21468/SciPostPhysCodeb.53
 
 * Example/DMRG:
-[https://www.tensors.net/dmrg](https://www.tensors.net/dmrg)
+https://www.tensors.net/dmrg
 
 * hptt library:
-[https://github.com/springer13/hptt](https://github.com/springer13/hptt)
+https://github.com/springer13/hptt

docs/.gitignore

@@ -6,5 +6,4 @@
 source/__pycache__/*
 tests/__pycache__/*
 tests/build/*
-build/
 *.swp

docs/api_doc_script.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/bash
+
+doxygen_build()
+{
+	VTAG=$1
+	echo $VTAG
+	git checkout $VTAG || {
+    echo "Failed to checkout tag $VTAG";
+    exit 1;
+	}
+	doxygen docs.doxygen > /dev/null 2>&1
+	if [ "$VTAG" = master ]; then
+		mkdir -p docs/api_docs/versions
+		VTAG=latest
+	fi
+	mv docs/html docs/api_docs/versions/$VTAG
+}
+
+# get current branch
+branch=$(git rev-parse --abbrev-ref HEAD)
+
+mkdir build
+cd ../
+
+# Build latest version
+doxygen_build master
+
+smallest_ver=0.7.3
+# Get all version latest than smallest_ver
+versions=($(git tag \
+  | sed 's/^v//' \
+  | sed 's/[A-Za-z].*$//' \
+  | sort -V \
+  | awk -F. -v cv="$smallest_ver" '
+      BEGIN { split(cv,c,"."); min=c[1]*10000+c[2]*100+c[3] }
+      { val=$1*10000+$2*100+$3; if(val>=min) print }
+  '))
+
+# Build older version latest from smallest_ver
+for i in "${!versions[@]}"; do
+  ver="v${versions[i]}"
+  doxygen_build $ver
+done
+
+# checkout original version
+git checkout $branch
+
+# Create index.rst
+cd ./docs/api_docs/home_source
+cat > index.rst <<'EOF'
+.. image:: Icon_small.png
+    :width: 350
+
+Cytnx API
+=================================
+    Cytnx is a library design for Quantum physics simulation using GPUs and CPUs.
+
+* `Latest version <versions/latest/index.html>`__.
+
+Older versions:
+
+EOF
+
+for ((i=${#versions[@]}-1; i>=0; i--)); do
+  ver="v${versions[i]}"
+	echo '	* `'$ver' <versions/'$ver'/index.html>`__.' >> index.rst
+done
+
+# build API documentation index.
+cd ../
+make html
+
+# move the api_build under build
+mv versions ./build_home/html/
+mv build_home ../build/api_build

docs/api_docs/.gitignore

@@ -0,0 +1,3 @@
+build_home/*
+home_source/index.rst
+*.swp

docs/api_docs/Makefile

@@ -0,0 +1,22 @@
+# 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     = home_source
+BUILDDIR      = build_home
+
+# 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)

docs/api_docs/home_source/conf.py

@@ -0,0 +1,127 @@
+import os,sys
+sys.path.append('.')
+
+
+
+html_theme = 'sphinxbootstrap4theme'
+import sphinxbootstrap4theme
+html_theme_path = [sphinxbootstrap4theme.get_path()]
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Cytnx API'
+copyright = '2019-, Kai-Hsin Wu'
+author = 'Kai-Hsin Wu'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+# https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html
+extensions = ['sphinx.ext.autosectionlabel']
+extensions.append('sphinx.ext.extlinks')
+extensions.append('sphinxcontrib.jquery')
+#extensions.append('sphinx.ext.imgmath')
+#extensions.append('ablog')
+extensions.append('sphinx.ext.mathjax')
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+html_logo = 'Icon_i.png'
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'pyramid'
+#html_theme = 'sphinx'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+
+
+
+html_theme_options = {
+    # Navbar style.
+    # Values: 'fixed-top', 'full' (Default: 'fixed-top')
+    'navbar_style' : 'fixed-top',
+
+    # Navbar link color modifier class.
+    # Values: 'dark', 'light' (Default: 'dark')
+    'navbar_color_class' : 'dark',
+
+    # Navbar background color class.
+    # Values: 'inverse', 'primary', 'faded', 'success',
+    #         'info', 'warning', 'danger' (Default: 'inverse')
+    #'navbar_bg_class' : 'inverse',
+
+    # Show global TOC in navbar.
+    # To display up to 4 tier in the drop-down menu.
+    # Values: True, False (Default: True)
+    'navbar_show_pages' : False,
+
+    # Link name for global TOC in navbar.
+    # (Default: 'Pages')
+    #'navbar_pages_title' : 'Pages',
+
+    # Specify a list of menu in navbar.
+    # Tuples forms:
+    #  ('Name', 'external url or path of pages in the document', boolean)
+    # Third argument:
+    # True indicates an external link.
+    # False indicates path of pages in the document.
+    'navbar_links' : [
+         ("User Guide", "../../html/index.html", True),
+         ("Github", "https://github.com/Cytnx-dev/Cytnx", True)
+    ],
+
+    # Total width(%) of the document and the sidebar.
+    # (Default: 80%)
+    'main_width' : '80%',
+
+    # Render sidebar.
+    # Values: True, False (Default: True)
+    'show_sidebar' : False,
+
+    # Render sidebar in the right of the document.
+    # Values：True, False (Default: False)
+    'sidebar_right': False,
+
+    # Fix sidebar.
+    # Values: True, False (Default: True)
+    'sidebar_fixed': False,
+
+    # Html table header class.
+    # Values: 'inverse', 'light' (Deafult: 'inverse')
+    'table_thead_class' : 'inverse',
+
+}

docs/code/CytnxGuide_PythonCodeExamples_2023_06_30.ipynb

@@ -1751,7 +1751,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Tsymm_diff=T-cytnx.Contracts([U,S,Vt]);\n",
+    "Tsymm_diff=T-cytnx.Contract([U,S,Vt]);\n",
     "\n",
     "Tsymm_diff.Norm()/T.Norm()"
    ]
@@ -1937,7 +1937,7 @@
    "id": "be4e27d5",
    "metadata": {},
    "source": [
-    "8.2. Contract(s)"
+    "8.2. Contract"
    ]
   },
   {
@@ -2025,9 +2025,9 @@
     "A2.relabels_([\"phy2\",\"v5\",\"v6\"])\n",
     "\n",
     "\n",
-    "# Use Contracts\n",
+    "# Use Contract\n",
     "\n",
-    "res = cytnx.Contracts(TNs = [A1,M,A2], order = \"(M,(A1,A2))\", optimal = False)\n",
+    "res = cytnx.Contract(TNs = [A1,M,A2], order = \"(M,(A1,A2))\", optimal = False)\n",
     "\n",
     "res.print_diagram()"
    ]

docs/code/cplusplus/doc_codes/guide_basic_obj_Storage_5_io_Save.cpp

@@ -1,3 +1,3 @@
 auto A = cytnx::Storage(4);
 A.fill(6);
-A.Save("S1");
+A.Save("S1.cyst");