add docs support

.github/workflows/badge.yml

+name: Badge Creation
+
+on:
+  push:
+    branches: [ main, 'badge/*', 'doc/*' ]
+  pull_request:
+    branches: [ main, 'badge/*', 'doc/*' ]
+
+jobs:
+  update-badges:
+    name: Update Badges
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ 3.7 ]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Download cloc
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y cloc
+      - name: Get the Numbers
+        run: |
+          cloc .
+          echo "CODE_LINES=$(./cloc.sh --loc)" >> $GITHUB_ENV
+          echo "COMMENT_LINES=$(./cloc.sh --percentage)%" >> $GITHUB_ENV
+      - name: Create Lines-of-Code-Badge
+        uses: schneegans/dynamic-badges-action@v1.0.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: ${{ secrets.BADGE_GIST_ID }}
+          filename: loc.json
+          label: Lines of Code
+          message: ${{ env.CODE_LINES }}
+          color: lightgrey
+      - name: Create Comments-Badge
+        uses: schneegans/dynamic-badges-action@v1.0.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: ${{ secrets.BADGE_GIST_ID }}
+          filename: comments.json
+          label: Comments
+          message: ${{ env.COMMENT_LINES }}
+          color: green
\ No newline at end of file

.github/workflows/doc.yml

+# This workflow will check flake style
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Docs Deploy
+
+on:
+  push:
+    branches: [ main, 'doc/*', 'dev/*' ]
+  pull_request:
+    branches: [ main, 'doc/*', 'dev/*' ]
+  release:
+    types: [ published ]
+
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ 3.7 ]
+
+    services:
+      plantuml:
+        image: plantuml/plantuml-server
+        ports:
+          - 18080:8080
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y make wget curl cloc graphviz
+          dot -V
+          python -m pip install -r requirements.txt
+          python -m pip install -r requirements-doc.txt
+      - name: Generate
+        env:
+          ENV_PROD: 'true'
+          PLANTUML_HOST: http://localhost:18080
+        run: |
+          git fetch --all --tags
+          git branch -av
+          git remote -v
+          git tag
+          plantumlcli -c
+          make pdocs
+          mv ./docs/build/html ./public
+      - name: Deploy to Github Page
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: doc-deploy # The branch the action should deploy to.
+          FOLDER: public # The folder the action should deploy.
+          CLEAN: true # Automatically remove deleted files from the deploy branch

.github/workflows/release.yml

+name: Package Release
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  release:
+    name: Publish to official pypi
+    runs-on: ${{ matrix.os }}
+    if: ${{ github.repository == 'opendilab/DI-treetensor' }}
+    strategy:
+      matrix:
+        os:
+          - 'ubuntu-18.04'
+        python-version:
+          - '3.8'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 20
+      - name: Set up python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up python dependences
+        run: |
+          pip install --upgrade pip
+          pip install --upgrade flake8 setuptools wheel twine
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          if [ -f requirements-test.txt ]; then pip install -r requirements-test.txt; fi
+          pip install --upgrade build
+      - name: Build packages
+        run: |
+          python -m build --sdist --wheel --outdir dist/
+      - name: Publish distribution 📦 to real PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_PASSWORD }}
\ No newline at end of file

.github/workflows/test.yml

+name: Code Test
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  unittest:
+    name: Code test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - 'ubuntu-18.04'
+        python-version:
+          - '3.6'
+          - '3.7'
+          - '3.8'
+          - '3.9'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 20
+      - name: Set up system dependences on linux
+        if: ${{ runner.os == 'Linux' }}
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y tree cloc wget curl make graphviz
+          sudo apt-get install -y libxml2-dev libxslt-dev python-dev  # need by pypy3
+          dot -V
+      - name: Set up python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade flake8 setuptools wheel twine
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+      - name: Test the basic environment
+        run: |
+          python -V
+          pip --version
+          pip list
+          tree .
+          cloc treetensor
+          cloc test
+      - name: Run unittest
+        env:
+          CI: 'true'
+        run: |
+          make unittest
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false

.gitignore

@@ -997,7 +997,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/source/_build/
 
 # PyBuilder
 .pybuilder/

docs/Makefile

+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS         ?=
+SPHINXBUILD        ?= $(shell which sphinx-build)
+SPHINXMULTIVERSION ?= $(shell which sphinx-multiversion)
+SOURCEDIR          ?= source
+BUILDDIR           ?= build
+
+# Minimal makefile for Sphinx documentation
+DIAGRAMS_MK := ${SOURCEDIR}/diagrams.mk
+DIAGRAMS    := $(MAKE) -f "${DIAGRAMS_MK}" SOURCE=${SOURCEDIR}
+GRAPHVIZ_MK := ${SOURCEDIR}/graphviz.mk
+GRAPHVIZ    := $(MAKE) -f "${GRAPHVIZ_MK}" SOURCE=${SOURCEDIR}
+DEMOS_MK    := ${SOURCEDIR}/demos.mk
+DEMOS       := $(MAKE) -f "${DEMOS_MK}" SOURCE=${SOURCEDIR}
+
+_CURRENT_PATH := ${PATH}
+_PROJ_DIR     := $(shell readlink -f ${CURDIR}/..)
+_LIBS_DIR     := $(shell readlink -f ${SOURCEDIR}/_libs)
+_SHIMS_DIR    := $(shell readlink -f ${SOURCEDIR}/_shims)
+
+.EXPORT_ALL_VARIABLES:
+
+PYTHONPATH = ${_PROJ_DIR}:${_LIBS_DIR}
+PATH       = ${_SHIMS_DIR}:${_CURRENT_PATH}
+NO_CONTENTS_BUILD = true
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# Put it first so that "make" without argument is like "make help".
+.PHONY: help contents build html prod clean sourcedir builddir Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+contents:
+	@$(DIAGRAMS) build
+	@$(GRAPHVIZ) build
+	@$(DEMOS) build
+build: html
+html: contents
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@touch "$(BUILDDIR)/html/.nojekyll"
+prod:
+	@NO_CONTENTS_BUILD='' $(SPHINXMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+	@cp main_page.html "$(BUILDDIR)/html/index.html"
+	@touch "$(BUILDDIR)/html/.nojekyll"
+
+clean:
+	@$(DIAGRAMS) clean
+	@$(GRAPHVIZ) clean
+	@$(DEMOS) clean
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+sourcedir:
+	@echo $(shell readlink -f ${SOURCEDIR})
+builddir:
+	@echo $(shell readlink -f ${BUILDDIR}/html)
\ No newline at end of file

docs/main_page.html

+<!DOCTYPE html>
+<html>
+<head>
+    <title>Redirecting to master branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="./main/index.html">
+</head>
+</html>
\ No newline at end of file

docs/source/_shims/treevalue

+#!/usr/bin/env python
+
+from treevalue.entry.cli import treevalue_cli
+
+if __name__ == '__main__':
+    treevalue_cli()

docs/source/_templates/page.html

+{% extends "!page.html" %}
+{% block body %}
+    {% if current_version and latest_version and current_version != latest_version %}
+        <p>
+            <strong>
+                {% if current_version.is_released %}
+                    You're reading an old version of this documentation.
+                    If you want up-to-date information, please have a look at
+                    <a href="{{ vpathto(latest_version.name) }}">{{ latest_version.name }}</a>.
+                {% else %}
+                    You're reading the documentation for a development version.
+                    For the latest released version, please have a look at
+                    <a href="{{ vpathto(latest_version.name) }}">{{ latest_version.name }}</a>.
+                {% endif %}
+            </strong>
+        </p>
+    {% endif %}
+    {{ super() }}
+{% endblock %}%
\ No newline at end of file

docs/source/_templates/versions.html

+{%- if current_version %}
+    <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+        <div class="rst-other-versions">
+            {%- if versions.tags %}
+                <dl>
+                    <dt>Tags</dt>
+                    {%- for item in versions.tags %}
+                        <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+                    {%- endfor %}
+                </dl>
+            {%- endif %}
+            {%- if versions.branches %}
+                <dl>
+                    <dt>Branches</dt>
+                    {%- for item in versions.branches %}
+                        <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+                    {%- endfor %}
+                </dl>
+            {%- endif %}
+        </div>
+    </div>
+{%- endif %}
\ No newline at end of file

docs/source/conf.py

+# 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 -----------------------------------------------------
+
+import os
+import sys
+from datetime import datetime
+from subprocess import Popen
+
+import where
+from packaging import version as version_
+
+# Get current location
+_DOC_PATH = os.path.dirname(os.path.abspath(__file__))
+_PROJ_PATH = os.path.abspath(os.path.join(_DOC_PATH, '..', '..'))
+_LIBS_PATH = os.path.join(_DOC_PATH, '_libs')
+_SHIMS_PATH = os.path.join(_DOC_PATH, '_shims')
+os.chdir(_PROJ_PATH)
+
+# Set environment, remove the pre-installed package
+sys.path.insert(0, _PROJ_PATH)
+modnames = [mname for mname in sys.modules if mname.startswith('treetensor')]
+for modname in modnames:
+    del sys.modules[modname]
+
+# Build dependencies if needed
+if not os.environ.get("NO_CONTENTS_BUILD"):
+    _env = dict(os.environ)
+    _env.update(dict(
+        PYTHONPATH=':'.join([_PROJ_PATH, _LIBS_PATH]),
+        PATH=':'.join([_SHIMS_PATH, os.environ.get('PATH', '')]),
+    ))
+
+    pip_cmd = (where.first('pip'), 'install', '-r', os.path.join(_PROJ_PATH, 'requirements.txt'))
+    print("Install pip requirements {cmd}...".format(cmd=repr(pip_cmd)))
+    pip = Popen(pip_cmd, stdout=sys.stdout, stderr=sys.stderr, env=_env, cwd=_DOC_PATH)
+    if pip.wait() != 0:
+        raise ChildProcessError("Pip install failed with %d." % (pip.returncode,))
+
+    pip_docs_cmd = (where.first('pip'), 'install', '-r', os.path.join(_PROJ_PATH, 'requirements-doc.txt'))
+    print("Install pip docs requirements {cmd}...".format(cmd=repr(pip_docs_cmd)))
+    pip_docs = Popen(pip_docs_cmd, stdout=sys.stdout, stderr=sys.stderr, env=_env, cwd=_DOC_PATH)
+    if pip_docs.wait() != 0:
+        raise ChildProcessError("Pip docs install failed with %d." % (pip.returncode,))
+
+    diagrams_cmd = (where.first('make'), '-f', "diagrams.mk", "build")
+    print("Building diagrams {cmd} at {cp}...".format(cmd=repr(diagrams_cmd), cp=repr(_DOC_PATH)))
+    diagrams = Popen(diagrams_cmd, stdout=sys.stdout, stderr=sys.stderr, env=_env, cwd=_DOC_PATH)
+    if diagrams.wait() != 0:
+        raise ChildProcessError("Diagrams failed with %d." % (diagrams.returncode,))
+
+    graphviz_cmd = (where.first('make'), '-f', "graphviz.mk", "build")
+    print("Building graphs {cmd} at {cp}...".format(cmd=repr(graphviz_cmd), cp=repr(_DOC_PATH)))
+    graphviz = Popen(graphviz_cmd, stdout=sys.stdout, stderr=sys.stderr, env=_env, cwd=_DOC_PATH)
+    if graphviz.wait() != 0:
+        raise ChildProcessError("Graphviz failed with %d." % (graphviz.returncode,))
+
+    demos_cmd = (where.first('make'), '-f', "demos.mk", "build")
+    print("Building demos {cmd} at {cp}...".format(cmd=repr(demos_cmd), cp=repr(_DOC_PATH)))
+    demos = Popen(demos_cmd, stdout=sys.stdout, stderr=sys.stderr, env=_env, cwd=_DOC_PATH)
+    if demos.wait() != 0:
+        raise ChildProcessError("Demos failed with %d." % (demos.returncode,))
+
+    print("Build of contents complete.")
+
+from treetensor.config.meta import __TITLE__, __AUTHOR__, __VERSION__
+
+project = __TITLE__
+copyright = '{year}, {author}'.format(year=datetime.now().year, author=__AUTHOR__)
+author = __AUTHOR__
+
+# The short X.Y version
+version = version_.parse(__VERSION__).base_version
+# The full version, including alpha/beta/rc tags
+release = __VERSION__
+
+# -- 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.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.todo',
+    'sphinx.ext.graphviz',
+    'enum_tools.autoenum',
+    "sphinx_multiversion",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+htmlhelp_basename = 'DI-TreeValue'
+
+# 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']
+
+epub_title = project
+epub_exclude_files = ['search.html']
+
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r'^v.*$'  # Include all tags start with 'v'
+smv_branch_whitelist = r'^.*$'  # Include all branches
+smv_remote_whitelist = r'^.*$'  # Use branches from all remotes
+smv_released_pattern = r'^tags/.*$'  # Tags only
+smv_outputdir_format = '{ref.name}'  # Use the branch/tag name
+
+if not os.environ.get("ENV_PROD"):
+    todo_include_todos = True
+    todo_emit_warnings = True

docs/source/demos.mk

+PYTHON := $(shell which python)
+
+SOURCE         ?= .
+PYTHON_DEMOS   := $(shell find ${SOURCE} -name *.demo.py)
+PYTHON_DEMOXS  := $(shell find ${SOURCE} -name *.demox.py)
+PYTHON_RESULTS := $(addsuffix .py.txt, $(basename ${PYTHON_DEMOS} ${PYTHON_DEMOXS}))
+
+SHELL_DEMOS    := $(shell find ${SOURCE} -name *.demo.sh)
+SHELL_DEMOXS   := $(shell find ${SOURCE} -name *.demox.sh)
+SHELL_RESULTS  := $(addsuffix .sh.txt, $(basename ${SHELL_DEMOS} ${SHELL_DEMOXS}))
+
+%.demo.py.txt: %.demo.py
+	cd "$(shell dirname $(shell readlink -f $<))" && \
+		PYTHONPATH="$(shell dirname $(shell readlink -f $<)):${PYTHONPATH}" \
+		$(PYTHON) "$(shell readlink -f $<)" > "$(shell readlink -f $@)"
+
+%.demox.py.txt: %.demox.py
+	cd "$(shell dirname $(shell readlink -f $<))" && \
+		PYTHONPATH="$(shell dirname $(shell readlink -f $<)):${PYTHONPATH}" \
+		$(PYTHON) "$(shell readlink -f $<)" 1> "$(shell readlink -f $@)" \
+		2> "$(shell readlink -f $(addsuffix .err, $(basename $@)))"; \
+		echo $$? > "$(shell readlink -f $(addsuffix .exitcode, $(basename $@)))"
+
+%.demo.sh.txt: %.demo.sh
+	cd "$(shell dirname $(shell readlink -f $<))" && \
+		PYTHONPATH="$(shell dirname $(shell readlink -f $<)):${PYTHONPATH}" \
+		$(SHELL) "$(shell readlink -f $<)" > "$(shell readlink -f $@)"
+
+%.demox.sh.txt: %.demox.sh
+	cd "$(shell dirname $(shell readlink -f $<))" && \
+		PYTHONPATH="$(shell dirname $(shell readlink -f $<)):${PYTHONPATH}" \
+		$(SHELL) "$(shell readlink -f $<)" 1> "$(shell readlink -f $@)" \
+		2> "$(shell readlink -f $(addsuffix .err, $(basename $@)))"; \
+		echo $$? > "$(shell readlink -f $(addsuffix .exitcode, $(basename $@)))"
+
+build: ${PYTHON_RESULTS} ${SHELL_RESULTS}
+
+all: build
+
+clean:
+	rm -rf \
+		$(shell find ${SOURCE} -name *.py.txt) \
+		$(shell find ${SOURCE} -name *.py.err) \
+		$(shell find ${SOURCE} -name *.py.exitcode) \
+		$(shell find ${SOURCE} -name *.sh.txt) \
+		$(shell find ${SOURCE} -name *.sh.err) \
+		$(shell find ${SOURCE} -name *.sh.exitcode) \
+		$(shell find ${SOURCE} -name *.dat.*)

docs/source/diagrams.mk

+PLANTUMLCLI ?= $(shell which plantumlcli)
+
+SOURCE ?= .
+PUMLS  := $(shell find ${SOURCE} -name *.puml)
+PNGS   := $(addsuffix .puml.png, $(basename ${PUMLS}))
+SVGS   := $(addsuffix .puml.svg, $(basename ${PUMLS}))
+
+%.puml.png: %.puml
+	$(PLANTUMLCLI) -t png -o "$(shell readlink -f $@)" "$(shell readlink -f $<)"
+
+%.puml.svg: %.puml
+	$(PLANTUMLCLI) -t svg -o "$(shell readlink -f $@)" "$(shell readlink -f $<)"
+
+build: ${SVGS} ${PNGS}
+
+all: build
+
+clean:
+	rm -rf \
+		$(shell find ${SOURCE} -name *.puml.svg) \
+		$(shell find ${SOURCE} -name *.puml.png) \

docs/source/graphviz.mk

+DOT := $(shell which dot)
+
+SOURCE ?= .
+GVS    := $(shell find ${SOURCE} -name *.gv)
+PNGS   := $(addsuffix .gv.png, $(basename ${GVS}))
+SVGS   := $(addsuffix .gv.svg, $(basename ${GVS}))
+
+%.gv.png: %.gv
+	$(DOT) -Tpng -o"$(shell readlink -f $@)" "$(shell readlink -f $<)"
+
+%.gv.svg: %.gv
+	$(DOT) -Tsvg -o"$(shell readlink -f $@)" "$(shell readlink -f $<)"
+
+build: ${SVGS} ${PNGS}
+
+all: build
+
+clean:
+	rm -rf \
+		$(shell find ${SOURCE} -name *.gv.svg) \
+		$(shell find ${SOURCE} -name *.gv.png) \

docs/source/index.rst

+.. DI-treetensor documentation master file, created by
+   sphinx-quickstart on Sun Sep  5 23:14:14 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to DI-treetensor's documentation!
+=========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`