Merge pull request #166 from Zhaoyilunnn/master

Update document to 0.4.0

.gitignore

@@ -23,5 +23,7 @@ src/site
 test
 thirdparty
 wheelhouse
-*.zhaoyilun
-*.png
+
+# documents
+doc/build
+doc/pages

doc/README.md

@@ -1,2 +1,15 @@
 # PyQuafu Documentation by Sphinx
 
+## Install Requirements
+
+```bash
+pip install -r requirements.txt
+```
+
+## Build
+
+Currently, this script can only run on Unix system
+
+```bash
+python run.py
+```

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==7.3.7
+sphinx-rtd-theme==2.0.0

doc/run.py

@@ -0,0 +1,35 @@
+import json
+import os
+import subprocess
+
+
+def build_doc(version, tag):
+    os.environ["current_version"] = version
+    subprocess.run("git checkout " + tag, shell=True)
+    subprocess.run("git checkout master -- source/conf.py", shell=True)
+    subprocess.run("git checkout master -- source/versions.json", shell=True)
+    subprocess.run("make html", shell=True)
+
+
+def move_dir(src, dst):
+    subprocess.run(["mkdir", "-p", dst])
+    subprocess.run("mv " + src + "* " + dst, shell=True)
+
+
+if __name__ == "__main__":
+    ## First clean dir
+    subprocess.run("rm -rf build/ pages/", shell=True)
+
+    os.environ["build_all_docs"] = str(True)
+    os.environ["pages_root"] = "https://scq-cloud.github.io"
+
+    build_doc("latest", "master")
+    move_dir("./build/html/", "./pages/")
+
+    with open("source/versions.json", "r") as json_file:
+        docs = json.load(json_file)
+
+    for version in docs:
+        tag = docs[version]["tag"]
+        build_doc(version, tag)
+        move_dir("./build/html/", "./pages/" + version)

doc/source/_templates/versions.html

@@ -0,0 +1,18 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    Version: {{ current_version }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {% if versions|length >= 1 %}
+    <dl>
+      <dt>{{ _('Versions') }}</dt>
+      {% for the_version, url in versions %}
+        <dd><a href="{{ url }}/index.html">{{ the_version }}</a></dd>
+      {% endfor %}
+    </dl>
+    {% endif %}
+    <br>
+    </dl>
+  </div>
+</div>

doc/source/conf.py

@@ -3,36 +3,57 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import json
+import os
+
 # -- package path -------------------------------------------
 import sys
-import os
 
-package_path = os.path.join(os.getcwd(), '..\\..\\src\\')
+package_path = os.path.join(os.getcwd(), "..\\..\\src\\")
 sys.path.insert(0, package_path)
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'PyQuafu-Docs'
-copyright = '2023, BAQIS-ScQ-Cloud'
-author = 'BAQIS-ScQ-Cloud'
-release = '0.3.6'
+project = "PyQuafu-Docs"
+copyright = "2023, BAQIS-ScQ-Cloud"
+author = "BAQIS-ScQ-Cloud"
+release = "0.4.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.napoleon'
-              ]  # 'sphinx.ext.autosummary'
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]  # 'sphinx.ext.autosummary'
 
-templates_path = ['_templates']
+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 = "sphinx_rtd_theme"
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Use Napoleon interpreter to support Google style docstrings
-autodoc_typehints = 'description'
+autodoc_typehints = "description"
+
+# Build multi-versions
+build_all_docs = os.environ.get("build_all_docs")
+pages_root = os.environ.get("pages_root", "")
+
+if build_all_docs is not None:
+    current_version = os.environ.get("current_version")
+
+    html_context = {
+        "current_version": current_version,
+        "versions": [
+            ["0.2.x", pages_root + "/0.2.x"],
+            ["0.3.x", pages_root + "/0.3.x"]
+        ],
+    }
+
+    with open("versions.json", "r") as json_file:
+        docs = json.load(json_file)
+
+    for version in docs:
+        html_context["versions"].append([version, pages_root + "/" + version])

doc/source/index.rst

@@ -6,21 +6,20 @@
 Welcome to PyQuafu's documentation!
 ======================================
 
-`Quafu <http://quafu.baqis.ac.cn/>`_ shares open access to 
-super-conducting quantum (ScQ) computing resources with public users from all around 
-the world. As the python SDK of `Quafu <http://quafu.baqis.ac.cn/>`_, ``pyquafu`` 
-provides not only flexible and advanced interfaces to the experimental backends, 
-but also useful toolkits for simulating, visualizing and more about quantum computation. 
-This documentation describes its basic syntax and usages. 
+`Quafu <http://quafu.baqis.ac.cn/>`_ shares open access to
+super-conducting quantum (ScQ) computing resources with public users from all around
+the world. As the python SDK of `Quafu <http://quafu.baqis.ac.cn/>`_, ``pyquafu``
+provides not only flexible and advanced interfaces to the experimental backends,
+but also useful toolkits for simulating, visualizing and more about quantum computation.
+This documentation describes its basic syntax and usages.
 
 Contents
 ====================================
 .. toctree::
    :maxdepth: 2
 
-   User Guide <user_guide/quafu_doc_0.3.5/quafu_doc_0_3_5>
-   API Reference <apiref/apiref_0.3.5>
-   Historical Version <release_note/historical_version>
+   Tutorial <tutorial>
+   API Reference <apiref>
 
 Links
 ====================================