From 243bee9656791aabafa516a379222799a1707098 Mon Sep 17 00:00:00 2001 From: Niels Bantilan Date: Tue, 30 Mar 2021 12:17:10 -0400 Subject: [PATCH] update docs theme (#133) * update docs theme Signed-off-by: cosmicBboy * add community link Signed-off-by: cosmicBboy --- _static/custom.css | 33 ++++++++++++++++++++++++ _templates/sidebar/brand.html | 18 +++++++++++++ conf.py | 48 +++++++++++++++++------------------ developing.rst | 4 +-- doc-requirements.in | 2 ++ doc-requirements.txt | 18 ++++++++----- index.rst | 30 ++++++++++------------ reference/index.rst | 24 ++++++++++++++++++ 8 files changed, 129 insertions(+), 48 deletions(-) create mode 100644 _static/custom.css create mode 100644 _templates/sidebar/brand.html create mode 100644 reference/index.rst diff --git a/_static/custom.css b/_static/custom.css new file mode 100644 index 0000000000..786fcd2611 --- /dev/null +++ b/_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/_templates/sidebar/brand.html b/_templates/sidebar/brand.html new file mode 100644 index 0000000000..a170d6c6d1 --- /dev/null +++ b/_templates/sidebar/brand.html @@ -0,0 +1,18 @@ + diff --git a/conf.py b/conf.py index 9f781c8f63..d5bbf7a621 100644 --- a/conf.py +++ b/conf.py @@ -47,6 +47,7 @@ "sphinx.ext.coverage", "sphinx-prompt", "sphinx_copybutton", + "sphinx_search.extension", ] # build the templated autosummary files @@ -79,10 +80,11 @@ # 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 ------------------------------------------------- @@ -90,41 +92,39 @@ # 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/developing.rst b/developing.rst index 3f9b6d466d..fc4175d549 100644 --- a/developing.rst +++ b/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/doc-requirements.in b/doc-requirements.in index cdb6725a1b..8a0e088122 100644 --- a/doc-requirements.in +++ b/doc-requirements.in @@ -1,3 +1,5 @@ +furo +readthedocs-sphinx-search sphinx sphinx-prompt sphinx-material diff --git a/doc-requirements.txt b/doc-requirements.txt index d5a288dbd0..d01f9385bf 100644 --- a/doc-requirements.txt +++ b/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,13 +45,15 @@ 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 @@ -56,11 +61,12 @@ 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/index.rst b/index.rst index 584ebaa525..cf6e78bd23 100644 --- a/index.rst +++ b/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 `_. The Specification contains +``FlyteIDL``: Flyte's Core Language Specification +=================================================== + +``FlyteIDL`` contains the core language specification of Flyte, using `Google's Protocol Buffers `_. The Specification contains #. The core specification for Flyte Workflows, tasks and the type system #. The specification for FlyteAdmin's `gRPC `_ and ``REST`` endpoints #. Some of the core plugin API's like - Spark, Sagemaker, etc -This specification is used to generate client stubs for `FlyteKit `_, `FlyteKit Java `_, `Flytectl `_ and the `FlyteAdmin Service `_. +This specification is used to generate client stubs for `FlyteKit `_, `FlyteKit Java `_, `Flytectl `_ and the `FlyteAdmin Service `_. + .. toctree:: :maxdepth: 1 - :caption: Flytekit Learn by Example + :hidden: - Flyte Documentation - Flytekit Learn by Example + Getting Started + Tutorials + reference/index + Community .. toctree:: :maxdepth: 2 - :caption: FlyteIDL API reference & Development + :caption: FlyteIDL + :hidden: + Overview gen/pb-protodoc/flyteidl/index developing - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/reference/index.rst b/reference/index.rst new file mode 100644 index 0000000000..6b6ff34c49 --- /dev/null +++ b/reference/index.rst @@ -0,0 +1,24 @@ +############# +API Reference +############# + +.. toctree:: + :maxdepth: 1 + :caption: API Reference + :name: apitoc + + Flytekit Python + Flytekit Java + FlyteIDL + Flytectl + +.. toctree:: + :maxdepth: 1 + :caption: Component Reference (Code docs) + :name: componentreftoc + + FlytePropeller + FlyteAdmin + FlytePlugins + DataCatalog + \ No newline at end of file