update docs theme (#133)

* update docs theme Signed-off-by: cosmicBboy <[email protected]> * add community link Signed-off-by: cosmicBboy <[email protected]>
flyteorg · Mar 30, 2021 · 12f9e8a · 12f9e8a
1 parent 0475f7a
commit 12f9e8a
Show file tree

Hide file tree

Showing 8 changed files with 129 additions and 48 deletions.
diff --git a/flyteidl/_static/custom.css b/flyteidl/_static/custom.css
@@ -0,0 +1,33 @@
+h1, h2, h3, h4, h5, h6 {
+    font-weight: bold;
+}
+
+.sidebar-logo {
+    max-width: 30%;
+}
+
+
+.sidebar-tree .reference.external:after {
+    content: none;
+}
+
+div.sphx-glr-download a {
+    color: #4300c9;
+    background-color: rgb(241, 241, 241);
+    background-image: none;
+    border: 1px solid rgb(202, 202, 202);
+}
+
+div.sphx-glr-download a:hover {
+    background-color: rgb(230, 230, 230);
+    box-shadow: none;
+}
+
+div.sphx-glr-thumbcontainer a.headerlink {
+    display: none;
+}
+
+div.sphx-glr-thumbcontainer:hover {
+    border-color: white;
+    box-shadow: none;
+}
diff --git a/flyteidl/_templates/sidebar/brand.html b/flyteidl/_templates/sidebar/brand.html
@@ -0,0 +1,18 @@
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ home_page }}">
+    {% block brand_content %}
+    {%- if logo %}
+    <div class="sidebar-logo-container">
+      <img class="sidebar-logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+    </div>
+    {%- endif %}
+    {%- if theme_light_logo and theme_dark_logo %}
+    <div class="sidebar-logo-container">
+      <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="Light Logo"/>
+      <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="Dark Logo"/>
+    </div>
+    {%- endif %}
+    {% if not theme_sidebar_hide_name %}
+    <span class="sidebar-brand-text">{{ docstitle }}</span>
+    {%- endif %}
+    {% endblock brand_content %}
+  </a>
diff --git a/flyteidl/conf.py b/flyteidl/conf.py
@@ -47,6 +47,7 @@
     "sphinx.ext.coverage",
     "sphinx-prompt",
     "sphinx_copybutton",
+    "sphinx_search.extension",
 ]
 
 # build the templated autosummary files
@@ -79,52 +80,51 @@
 # 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 = []
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "tango"
+pygments_dark_style = "paraiso-dark"
 
 
 # -- 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_material"
+html_theme = "furo"
+html_title = "Flyte Docs"
 html_logo = "docs/images/flyte_circle_gradient_1_4x4.png"
+
 html_theme_options = {
-    # Set the name of the project to appear in the navigation.
-    "nav_title": "Flyte",
-    # Set you GA account ID to enable tracking
-    "google_analytics_account": "G-YQL24L5CKY",
-    # Specify a base_url used to generate sitemap.xml. If not
-    # specified, then no sitemap will be built.
-    "base_url": "https://github.com/flyteorg/flyteidl",
-    # Set the color and the accent color
-    "color_primary": "deep-purple",
-    "color_accent": "blue",
-    # Set the repo location to get a badge with stats
-    "repo_url": "https://github.com/flyteorg/flyte/",
-    "repo_name": "flyte",
-    # Visible levels of the global TOC; -1 means unlimited
-    "globaltoc_depth": 1,
-    # If False, expand all TOC entries
-    "globaltoc_collapse": False,
-    # If True, show hidden TOC entries
-    "globaltoc_includehidden": False,
+    "light_css_variables": {
+        "color-brand-primary": "#4300c9",
+        "color-brand-content": "#4300c9",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#9D68E4",
+        "color-brand-content": "#9D68E4",
+    },
+}
+
+html_context = {
+    "home_page": "https://docs.flyte.org",
 }
 
 # The default sidebars (for documents that don't match any pattern) are
 # defined by theme itself.  Builtin themes are using these templates by
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
-html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}
+# html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}
 
 
 # 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 = []
+html_static_path = ["_static"]
+html_css_files = [
+    "custom.css",
+]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

diff --git a/flyteidl/developing.rst b/flyteidl/developing.rst
@@ -1,5 +1,5 @@
-How to contribute to and develop Flyte IDL
-===========================================
+Contributing to Flyte IDL
+=========================
 
 Generate Code from protobuf
 ----------------------------

diff --git a/flyteidl/doc-requirements.in b/flyteidl/doc-requirements.in
@@ -1,3 +1,5 @@
+furo
+readthedocs-sphinx-search
 sphinx
 sphinx-prompt
 sphinx-material

diff --git a/flyteidl/doc-requirements.txt b/flyteidl/doc-requirements.txt
@@ -10,6 +10,7 @@ babel==2.9.0
     # via sphinx
 beautifulsoup4==4.9.3
     # via
+    #   furo
     #   sphinx-code-include
     #   sphinx-material
 certifi==2020.12.5
@@ -20,19 +21,21 @@ css-html-js-minify==2.5.5
     # via sphinx-material
 docutils==0.16
     # via sphinx
+furo==2021.3.20b30
+    # via -r doc-requirements.in
 idna==2.10
     # via requests
 imagesize==1.2.0
     # via sphinx
 jinja2==2.11.3
     # via sphinx
-lxml==4.6.2
+lxml==4.6.3
     # via sphinx-material
 markupsafe==1.1.1
     # via jinja2
 packaging==20.9
     # via sphinx
-pygments==2.7.4
+pygments==2.8.1
     # via
     #   sphinx
     #   sphinx-prompt
@@ -42,25 +45,28 @@ python-slugify[unidecode]==4.0.1
     # via sphinx-material
 pytz==2021.1
     # via babel
+readthedocs-sphinx-search==0.1.0
+    # via -r doc-requirements.in
 requests==2.25.1
     # via sphinx
 six==1.15.0
     # via sphinx-code-include
 snowballstemmer==2.1.0
     # via sphinx
-soupsieve==2.1
+soupsieve==2.2.1
     # via beautifulsoup4
 sphinx-code-include==1.1.1
     # via -r doc-requirements.in
 sphinx-copybutton==0.3.1
     # via -r doc-requirements.in
 sphinx-material==0.0.32
     # via -r doc-requirements.in
-sphinx-prompt==1.3.0
+sphinx-prompt==1.4.0
     # via -r doc-requirements.in
-sphinx==3.4.3
+sphinx==3.5.3
     # via
     #   -r doc-requirements.in
+    #   furo
     #   sphinx-code-include
     #   sphinx-copybutton
     #   sphinx-material
@@ -81,7 +87,7 @@ text-unidecode==1.3
     # via python-slugify
 unidecode==1.2.0
     # via python-slugify
-urllib3==1.26.3
+urllib3==1.26.4
     # via requests
 
 # The following packages are considered to be unsafe in a requirements file:

diff --git a/flyteidl/index.rst b/flyteidl/index.rst
@@ -1,33 +1,31 @@
 .. flyteidl documentation master file, created by
 
-Welcome to ``FlyteIDL - Flytes Languages Specification`` documentation!
-=========================================================================
-FlyteIDL contains the core specification of Flyte, using `Googles Protocol Buffers <https://developers.google.com/protocol-buffers>`_. The Specification contains
+``FlyteIDL``: Flyte's Core Language Specification
+===================================================
+
+``FlyteIDL`` contains the core language specification of Flyte, using `Google's Protocol Buffers <https://developers.google.com/protocol-buffers>`_. The Specification contains
 
 #. The core specification for Flyte Workflows, tasks and the type system
 #. The specification for FlyteAdmin's `gRPC <https://grpc.io/>`_ and ``REST`` endpoints
 #. Some of the core plugin API's like - Spark, Sagemaker, etc
 
-This specification is used to generate client stubs for `FlyteKit <https://flyte.readthedocs.io/projects/flytekit/en/master/>`_, `FlyteKit Java <https://github.com/spotify/flytekit-java>`_, `Flytectl <https://github.com/flyteorg/flytectl>`_ and the `FlyteAdmin Service <https://pkg.go.dev/github.com/lyft/flyteadmin>`_.
+This specification is used to generate client stubs for `FlyteKit <https://flyte.readthedocs.io/projects/flytekit>`_, `FlyteKit Java <https://github.com/spotify/flytekit-java>`_, `Flytectl <https://github.com/flyteorg/flytectl>`_ and the `FlyteAdmin Service <https://pkg.go.dev/github.com/lyft/flyteadmin>`_.
+
 
 .. toctree::
    :maxdepth: 1
-   :caption: Flytekit Learn by Example
+   :hidden:
 
-   Flyte Documentation <https://flyte.readthedocs.io/en/latest/>
-   Flytekit Learn by Example <http://flytecookbook.readthedocs.io/>
+   Getting Started <https://docs.flyte.org/en/latest/getting_started.html>
+   Tutorials <https://flytecookbook.readthedocs.io>
+   reference/index
+   Community <https://docs.flyte.org/en/latest/community/index.html>
 
 .. toctree::
    :maxdepth: 2
-   :caption: FlyteIDL API reference & Development
+   :caption: FlyteIDL
+   :hidden:
 
+   Overview <self>
    gen/pb-protodoc/flyteidl/index
    developing
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/flyteidl/reference/index.rst b/flyteidl/reference/index.rst
@@ -0,0 +1,24 @@
+#############
+API Reference
+#############
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+   :name: apitoc
+
+   Flytekit Python <https://flytekit.readthedocs.io>
+   Flytekit Java <https://github.com/spotify/flytekit-java>
+   FlyteIDL <https://flyteidl.readthedocs.io>
+   Flytectl <https://flytectl.readthedocs.io>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Component Reference (Code docs)
+   :name: componentreftoc
+
+   FlytePropeller <https://pkg.go.dev/mod/github.com/flyteorg/flytepropeller>
+   FlyteAdmin <https://pkg.go.dev/mod/github.com/flyteorg/flyteadmin>
+   FlytePlugins <https://pkg.go.dev/mod/github.com/flyteorg/flyteplugins>
+   DataCatalog <https://pkg.go.dev/mod/github.com/flyteorg/datacatalog>
+