Multi-version docs. (#201)

.github/workflows/docs.yml

@@ -10,6 +10,7 @@ jobs:
       uses: actions/checkout@v2
       with:
         submodules: true
+        fetch-depth: 0
 
     - name: Cpp Format and Lint Check
       run: |
@@ -68,8 +69,18 @@ jobs:
         # Install pip dependencies, build builtin gar, and generate proto stuffs.
         sudo apt update
         sudo apt install -y doxygen
+
+        # generate a taged version
         make graphscope-docs
 
+        # generate a stable version
+        tag=$(git describe --exact-match --tags HEAD 2>/dev/null || true)
+        if [ ! -z "tag" ];
+        then
+          export TAG_VER=stable
+          make graphscope-docs
+        fi
+
     - name: Upload Docs
       if: ${{ github.ref == 'refs/heads/main' }}
       shell: bash
@@ -81,10 +92,29 @@ jobs:
 
         git fetch origin gh-pages --no-recurse-submodules
         git checkout gh-pages
+
         cd docs/
-        rm -rf !(_build)
-        mv _build/html/* ./
-        mv _build/html/.nojekyll ./
+        rm -rf !(_build|latest|stable|v*)
+
+        if [ -d "_build/latest" ];
+        then
+            rm -rf latest
+            cp -R _build/latest/html ./latest
+        else
+            tag=$(git describe --exact-match --tags HEAD)
+
+            rm -rf latest
+            cp -R _build/${tag}/html ./latest
+
+            rm -rf ${tag}
+            cp -R _build/${tag}/html ./${tag}
+        fi
+
+        if [ -d "_build/stable" ];
+        then
+            cp -R _build/stable/html/* ./
+        fi
+
         rm -rf _build/
         rm -rf ../learning_engine/ || true
         rm -rf ../python || true

docs/Makefile

@@ -8,6 +8,14 @@ SPHINXBUILD   ?= python3 -m sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+TAG 		  ?= $(TAG_VER)
+ifeq ($(strip $(TAG)),)
+	TAG 	  = $(shell git describe --exact-match --tags HEAD 2>/dev/null)
+endif
+ifeq ($(strip $(TAG)),)
+	TAG		  = latest
+endif
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -20,10 +28,10 @@ clean:
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile doxygen
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: Makefile
+	@echo "Tag is:" $(TAG)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)/$(TAG)" $(SPHINXOPTS) $(O)
 
 doxygen:
 	@mkdir -p _build
 	@doxygen Doxyfile
-

docs/_templates/layout.html

@@ -44,15 +44,59 @@
   <div class="rst-versions shift-up" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
       <span class="fa fa-book"> Read the Docs</span>
-      v: latest
+      v: {{ version }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
+      <dl>
+        <dt>{{ _('Versions') }}</dt>
+        {% for ver in versions %}
+          {% if ver == "stable" %}
+
+            {% if version == "stable" %}
+              {% if 'zh' in pagename %}
+                <dd><a href="{{ pathto('zh/index.html', 1) }}">{{ ver }}</a></dd>
+              {% else %}
+                <dd><a href="{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
+              {% endif %}
+            {% else %}
+              {% if 'zh' in pagename %}
+                <dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), 'zh') }}/index.html">{{ ver }}</a></dd>
+              {% else %}
+                <dd><a href="../{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
+              {% endif %}
+            {% endif %}
+
+          {% else %}
+
+            {% if version == "stable" %}
+              {% if 'zh' in pagename %}
+                <dd><a href="../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
+              {% else %}
+                <dd><a href="{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
+              {% endif %}
+            {% else %}
+              {% if 'zh' in pagename %}
+                <dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
+              {% else %}
+                <dd><a href="../{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
+              {% endif %}
+            {% endif %}
+
+          {% endif %}
+        {% endfor %}
+      </dl>
+
       <dl>
         <dt>{{ _('Languages') }}</dt>
         <dd><a href="{{ pathto('index.html', 1) }}">en</a></dd>
         <dd><a href="{{ pathto('zh/index.html', 1) }}">zh_CN</a></dd>
       </dl>
+
+      <hr />
+      <small>
+        <span>Hosted by <a href="https://pages.github.com/">Github Pages</a>.</span>
+      </small>
     </div>
   </div>
 {% endblock %}

docs/conf.py

@@ -13,6 +13,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../python'))
+sys.path.append(os.path.abspath('./'))
 
 # -- Project information -----------------------------------------------------
 

docs/loading_graph.rst

@@ -163,6 +163,7 @@ If there is only one vertex label in the graph, the label of vertices can be omi
 GraphScope will infer the source and destination vertex label is that very label.
 
 .. code:: python
+
     graph = sess.g()
     graph = graph.add_vertices("file:///home/admin/student.v", label="student")
     graph = graph.add_edges("file:///home/admin/group.e", label="group")

docs/reference/selector.rst

@@ -93,8 +93,8 @@ Note that selectors of :class:`VertexPropertyContext` only differed in `r` with
         - `r.column_name`: Get the property named `column_name` in results. e.g. `r.hub` in :func:`graphscope.hits`.
 
 
-LabelVertexPropertyContext
-++++++++++++++++++++++++++
+LabeledVertexPropertyContext
+++++++++++++++++++++++++++++
 
 :class:`LabeledVertexPropertyContext` is used by algorithms that compatible graphs is a property graph.
 i.e. There are several labels in the graph, and each label has several properties.

docs/sphinx_ext.py

@@ -16,10 +16,30 @@
 # limitations under the License.
 #
 
+import os
 import sphinx
 from sphinx import addnodes
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.environment.adapters.toctree import TocTree
+import subprocess
+
+
+def resolve_git_tags():
+    try:
+        head = subprocess.check_output(['git', 'describe', '--exact-match', '--tags', 'HEAD'], stderr=subprocess.DEVNULL)
+        head = head.decode('utf-8').strip()
+    except:
+        head = 'latest'
+    releases = subprocess.check_output(['git', 'tag', '--list', '--sort=-creatordate']).decode('utf-8').strip().split()
+    return head, releases
+
+
+def concat_path(page, base):
+    if '/' in page:
+        return page[:(page.rfind('/') + 1)] + base
+    else:
+        return base
+
 
 class TocTreeExt(TocTree):
     def get_local_toctree_for(self, master_doc, docname, builder, collapse, **kwargs):
@@ -59,6 +79,14 @@ def _get_local_toctree_ext(self, master_doc, pagename, collapse, **kwargs):
             master_doc, pagename, self, collapse, **kwargs))['fragment']
 
     def handle_page(self, pagename, *args, **kwargs):
+        version, releases = resolve_git_tags()
+        if os.environ.get('TAG_VER', None) == 'stable':
+            version = 'stable'
+        self.globalcontext['version'] = version
+        self.globalcontext['stable'] = releases[0]
+        self.globalcontext['versions'] = ['latest', 'stable'] + releases
+
+        self.globalcontext['concat_path'] = concat_path
         self.globalcontext['toctree_for'] = lambda master_doc, **kwargs: self._get_local_toctree_ext(master_doc, pagename, **kwargs)
         return super(StandaloneHTMLBuilderExt, self).handle_page(pagename, *args, **kwargs)
 

docs/zh/getting_started.rst

@@ -66,6 +66,7 @@
 对于 macOS，创建会话需要使用 LoadBalancer 服务类型（默认是 NodePort）。
 
 .. code:: python
+
     sess = graphscope.session(k8s_volumes=k8s_volumes, k8s_service_type="LoadBalancer")
 
 

docs/zh/loading_graph.rst

@@ -165,6 +165,7 @@ GraphScope 以
 GraphScope 将会推断起始点标签和终点标签为这一个点标签。
 
 .. code:: python
+
     graph = sess.g()
     graph = graph.add_vertices("file:///home/admin/student.v", label="student")
     graph = graph.add_edges("file:///home/admin/group.e", label="group")

python/graphscope/framework/context.py

@@ -102,16 +102,16 @@ def to_numpy(self, selector, vertex_range=None, axis=0):
         """Return context data as numpy array
 
         Args:
-        selector (str): Describes how to select values of context.
-            See more details in derived context class.
-        vertex_range (dict): optional, default to None.
-            Works as slicing. The expression {'begin': m, 'end': n} select a portion
-            of vertices from `m` to, but not including `n`. Type of `m`, `n` must be identical with vertices'
-            oid type.
-            Omitting the first index starts the slice at the beginning of the vertices,
-            and omitting the second index extends the slice to the end of the vertices.
-            Note the comparision is not based on numeric order, but on alphabetic order.
-        axis (int): optional, default to 0.
+            selector (str): Describes how to select values of context.
+                See more details in derived context class.
+            vertex_range (dict): optional, default to None.
+                Works as slicing. The expression {'begin': m, 'end': n} select a portion
+                of vertices from `m` to, but not including `n`. Type of `m`, `n` must be identical with vertices'
+                oid type.
+                Omitting the first index starts the slice at the beginning of the vertices,
+                and omitting the second index extends the slice to the end of the vertices.
+                Note the comparision is not based on numeric order, but on alphabetic order.
+            axis (int): optional, default to 0.
 
         Returns:
             numpy.ndarray.
@@ -211,6 +211,7 @@ def output(self, fd, selector, vertex_range=None, **kwargs):
         It first write results to a vineyard dataframe, and let vineyard
         do the data dumping job.
         `fd` must meet specific formats, with auth information if needed. As follows:
+
             - local
                 `file:///tmp/result_path`
             - oss
@@ -348,7 +349,7 @@ def _transform_selector(self, selector):
         return utils.transform_vertex_property_data_selector(selector)
 
 
-class LabelVertexPropertyContext(BaseContext):
+class LabeledVertexPropertyContext(BaseContext):
     """The labeld kind of context with properties.
     This context has several vertex labels and edge labels,
     And each label has several properties.
@@ -387,6 +388,6 @@ def create_context(context_type, session_id, context_key, graph):
     elif context_type == "vertex_property":
         return VertexPropertyContext(session_id, context_key, graph)
     elif context_type == "labeled_vertex_property":
-        return LabelVertexPropertyContext(session_id, context_key, graph)
+        return LabeledVertexPropertyContext(session_id, context_key, graph)
     else:
         raise InvalidArgumentError("Not supported context type: " + context_type)

python/graphscope/framework/graph.py

@@ -78,6 +78,7 @@ def __init__(
             session_id (str): Session id of the session the graph is created in.
             incoming_data: Graph can be initialized through various type of sources,
                 which can be one of:
+
                     - :class:`Operation`
                     - :class:`nx.Graph`
                     - :class:`Graph`
@@ -820,6 +821,7 @@ def add_edges(
     ):
         """Add edges to graph.
         1. Add edges to a uninitialized graph.
+
             i.   src_label and dst_label both unspecified. In this case, current graph must
                  has 0 (we deduce vertex label from edge table, and set vertex label name to '_'),
                  or 1 vertex label (we set src_label and dst label to this).
@@ -828,6 +830,7 @@ def add_edges(
                  we deduce all vertex labels from edge tables.
                  Note that you either provide all vertex labels, or let graphscope deduce all vertex labels.
                  We don't support mixed style.
+
         2. Add edges to a existed graph.
             Must add a new kind of edge label, not a new relation to builded graph.
             But you can add a new relation to uninitialized part of the graph.

python/graphscope/framework/loader.py

@@ -96,6 +96,7 @@ def __init__(self, source, delimiter=",", header_row=True, **kwargs):
         """Initialize a loader with configurable options.
         Note: Loader cannot be reused since it may change inner state when constructing
         information for loading a graph.
+
         Args:
             source (str or value):
                 The data source to be load, which could be one of the followings: