Update the vineyard documentation using the furo theme. (#816)

Signed-off-by: Tao He <linzhu.ht@alibaba-inc.com>
v6d-io · Jul 4, 2022 · 340cf25 · 340cf25
1 parent 79178f4
commit 340cf25
Show file tree

Hide file tree

Showing 33 changed files with 1,057 additions and 296 deletions.
diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml
@@ -90,7 +90,7 @@ jobs:
 
           # install python packages for codegen, and io adaptors
           sudo pip3 install -U "Pygments>=2.4.1"
-          sudo pip3 install -U libclang parsec sphinx sphinx_rtd_theme docutils==0.16 breathe nbsphinx gcovr pytest hdfs3 "numpy>=0.18.5"
+          sudo pip3 install -r requirements-setup.txt -r requirements.txt -r requirements-dev.txt
 
           # install linters
           sudo pip3 install auditwheel black isort flake8

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -78,9 +78,7 @@ jobs:
 
           # install python packages for codegen, and io adaptors
           sudo pip3 install -U "Pygments>=2.4.1"
-          sudo pip3 install libclang parsec pyarrow \
-               "sphinx==4.0.3" sphinx_rtd_theme docutils==0.16 breathe==4.30.0 nbsphinx gcovr pytest hdfs3 \
-               "numpy>=0.18.5" pandas pickle5 setuptools sortedcontainers psutil "jinja2>=3.0.0"
+          sudo pip3 install -r requirements-setup.txt -r requirements.txt -r requirements-dev.txt
 
           # linters
           sudo pip3 install black isort flake8

diff --git a/README.rst b/README.rst
@@ -1,7 +1,7 @@
 .. raw:: html
 
     <h1 align="center">
-        <img src="https://v6d.io/_static/vineyard-logo.png" width="397" alt="vineyard">
+        <img src="https://v6d.io/_static/vineyard-logo-rect.png" width="397" alt="vineyard">
     </h1>
     <p align="center">
         an in-memory immutable data manager

diff --git a/docs/_static/css/brands.min.css b/docs/_static/css/brands.min.css
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,8 @@
+.fa.fa-2x {
+    font-size: 36px;
+}
+
+/* Decrease the padding of button block in panels */
+div.card-body.card-body-less-padding {
+    padding: 0.25em;
+}
diff --git a/docs/_static/css/panels.css b/docs/_static/css/panels.css
@@ -0,0 +1,147 @@
+/* Referred and derived from https://github.com/flyteorg/furo/blob/main/src/furo/assets/styles/flyte.css */
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-weight: bold;
+}
+
+.caption-text {
+  font-size: 15px;
+  /* color: #696969; */
+  color: #333333;
+}
+
+div.sphinx-bs .card {
+  flex-direction: row;
+}
+
+/* sphinx-panels custom styles */
+div.sphinx-bs .card-header {
+  border-bottom: none;
+  background-color: var(--color-background-primary);
+  display: flex;
+  align-items: center;
+  justify-content: left;
+  width: 28%;
+  float: left;
+}
+
+.sphinx-bs .card-header:first-child {
+  border-radius: calc(0.25rem - 1px) 0 0 calc(0.25rem - 1px);
+}
+
+div.sphinx-bs .card-header .sphinx-bs.btn,
+div.sphinx-bs .card-body .sphinx-bs.btn,
+div.sphinx-bs .card-header p.card-text {
+  font-size: 1rem;
+  text-decoration: none;
+  word-spacing: 2.5px;
+  color: var(--color-sidebar-link-text);
+}
+
+div.sphinx-bs .card-header p.card-text a {
+  text-align: left;
+}
+
+.sphinx-bs.btn:focus {
+  box-shadow: none;
+}
+
+div.sphinx-bs .card-body {
+  width: 72%;
+  float: left;
+}
+
+.sphinx-bs .card-body .fa {
+  color: var(--color-sidebar-link-text);
+}
+
+.sphinx-bs .card-body:hover .fa {
+  color: var(--color-link--hover);
+}
+
+.sphinx-bs .card-body .fa {
+  font-size: 2rem;
+}
+
+div.sphinx-bs .card:hover {
+  box-shadow: none !important;
+  border-color: #cca9ff;
+}
+
+div.sphinx-bs .card:hover .card-header {
+  background-color: #f2e9ff;
+  color: #fff;
+}
+
+body[data-theme="dark"] div.sphinx-bs .card:hover {
+  border-color: #2a144a;
+}
+
+body[data-theme="dark"] div.sphinx-bs .card:hover .card-header {
+  background-color: #2a144a;
+  color: #fff;
+}
+
+/* make sure hover style is consistent if user prefers dark theme at OS level */
+@media (prefers-color-scheme: dark) {
+  body:not([data-theme="light"]) div.sphinx-bs .card:hover {
+    border-color: #2a144a;
+  }
+  body:not([data-theme="light"]) div.sphinx-bs .card:hover .card-header {
+    background-color: #2a144a;
+    color: #fff;
+  }
+}
+
+div.sphinx-bs .card:hover .sphinx-bs.btn {
+  color: var(--color-link);
+}
+
+div.sphinx-bs .card:hover .card-body .sphinx-bs.btn {
+  color: var(--color-link--hover);
+}
+
+.getting-started-panels div.sphinx-bs .sphinx-bs.btn:hover {
+  border-color: var(--color-link);
+  background-color: #9d68e4;
+  color: #ffffff;
+}
+
+div.sphinx-bs .card {
+  background-color: var(--color-background-secondary);
+  border: 1px solid var(--color-background-border);
+}
+
+.center-card-content p {
+  margin: auto !important;
+}
+
+.sphinx-tabs {
+  padding-top: 10px;
+}
+
+.sphinx-tabs-tab {
+  color: var(--color-link);
+}
+
+/* sphinx tabs */
+.sphinx-tabs-tab[aria-selected="true"] {
+  background-color: var(--color-background-secondary);
+  border: 1px solid var(--color-background-border);
+  border-bottom: 1px solid var(--color-background-secondary);
+}
+
+.sphinx-tabs-panel {
+  border: 1px solid var(--color-background-border);
+  background: var(--color-background-secondary);
+  border-top: 0;
+}
+
+[role="tablist"] {
+  border-bottom: 1px solid var(--color-background-border);
+}
diff --git a/docs/_static/css/v4-shims.min.css b/docs/_static/css/v4-shims.min.css
diff --git a/docs/_static/webfonts/fa-brands-400.ttf b/docs/_static/webfonts/fa-brands-400.ttf
diff --git a/docs/_static/webfonts/fa-brands-400.woff2 b/docs/_static/webfonts/fa-brands-400.woff2
diff --git a/docs/api-reference.rst b/docs/api-reference.rst
@@ -0,0 +1,62 @@
+API Reference
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: TOC
+   :hidden:
+
+   notes/python-api.rst
+   notes/cpp-api.rst
+   notes/ctl.rst
+
+Vineyard currently is distributed with a Python SDK and a C++ SDK. You could find a
+detail API reference from in the following pages:
+
+.. panels::
+   :header: text-center
+   :column: col-lg-12 p-2
+
+   .. link-button:: notes/python-api
+      :type: ref
+      :text: Python
+      :classes: btn-block stretched-link
+   ^^^^^^^^^^^^
+   API reference for vineyard Python SDK.
+
+   ---
+
+   .. link-button:: notes/cpp-api
+      :type: ref
+      :text: C++
+      :classes: btn-block stretched-link
+   ^^^^^^^^^^^^
+   API reference for vineyard C++ SDK.
+
+Besides, a command-line tool `vineyard-ctl` is provided to ease the interaction
+with local :code:`vineyardd` instance for inspecting and debugging propose.
+
+.. panels::
+   :header: text-center
+   :column: col-lg-12 p-2
+
+   .. link-button:: notes/ctl
+      :type: ref
+      :text: Vineyard CTL
+      :classes: btn-block stretched-link
+   ^^^^^^^^^^^^
+   Reference for vineyard command line tools.
+
+All terms in the documentation site can use search from the following
+indexing page:
+
+.. panels::
+   :header: text-center
+   :column: col-lg-12 p-2
+
+   .. link-button:: genindex
+      :type: ref
+      :text: API Indexes
+      :classes: btn-block stretched-link
+   ^^^^^^^^^^^^
+   Term indexes for the vineyard documentation.
diff --git a/docs/community.rst b/docs/community.rst
@@ -0,0 +1,83 @@
+Join the Community
+------------------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: TOC
+   :hidden:
+
+   notes/contributing.rst
+   notes/faq.rst
+   notes/troubleshooting.rst
+   notes/roadmap.rst
+
+Vineyard is an open-source project and has been accepted by CNCF sandbox in April, 2021,
+and indeed made successfully by the open-source community. We are striving to engage
+people in the community to help us make vineyard better and you could find the community
+welcoming and responsible by join our Github discussion or Slack channel:
+
+.. panels::
+    :container: container-lg pb-4
+    :column: col-lg-4 col-md-4 col-sm-4 col-xs-12 p-2
+    :body: text-center
+
+    .. link-button:: https://github.com/v6d-io/v6d/discussions
+       :type: url
+       :text: Github Discussions
+       :classes: btn-block stretched-link
+
+    :fa:`github`
+
+    ---
+
+    .. link-button:: http://slack.cncf.io
+       :type: url
+       :text: Slack
+       :classes: btn-block stretched-link
+
+    :fa:`slack`
+
+We have collected frequently asked questions from our users and you can find a detail
+list at
+
+.. panels::
+    :container: container-lg pb-4
+    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 p-2
+    :body: text-center card-body-less-padding
+
+    .. link-button:: notes/faq
+       :type: ref
+       :text: Frequently Asked Questions
+       :classes: btn-block stretched-link
+
+When encounter troubles during your journal of vineyard, you may find answers from:
+
+.. panels::
+    :container: container-lg pb-4
+    :column: col-lg-4 col-md-4 col-sm-4 col-xs-12 p-2
+    :body: text-center card-body-less-padding
+
+    .. link-button:: notes/troubleshooting
+       :type: ref
+       :text: Troubleshooting
+       :classes: btn-block stretched-link
+
+    ---
+
+    .. link-button:: https://github.com/v6d-io/v6d/issues
+       :type: url
+       :text: Github Issues
+       :classes: btn-block stretched-link
+
+Finally, we have a public roadmap that lists the directions we are striving towards and
+reflects our where ongoing efforts are happening:
+
+.. panels::
+    :container: container-lg pb-4
+    :column: col-lg-4 col-md-4 col-sm-4 col-xs-12 p-2
+    :body: text-center card-body-less-padding
+
+    .. link-button:: notes/roadmap
+       :type: ref
+       :text: Our Roadmap
+       :classes: btn-block stretched-link