From 1468b6b495bd4d7fe198aa4d44d209a8970a3d7c Mon Sep 17 00:00:00 2001 From: Niels Bantilan Date: Tue, 30 Mar 2021 15:22:53 -0400 Subject: [PATCH] update docs theme (#44) Signed-off-by: cosmicBboy --- flytectl/doc-requirements.in | 2 + flytectl/doc-requirements.txt | 18 ++++--- flytectl/docs/source/_static/custom.css | 33 +++++++++++++ .../docs/source/_templates/sidebar/brand.html | 18 +++++++ flytectl/docs/source/conf.py | 49 ++++++++++--------- flytectl/docs/source/index.rst | 49 ++++++++++--------- flytectl/docs/source/reference/index.rst | 24 +++++++++ 7 files changed, 141 insertions(+), 52 deletions(-) create mode 100644 flytectl/docs/source/_static/custom.css create mode 100644 flytectl/docs/source/_templates/sidebar/brand.html create mode 100644 flytectl/docs/source/reference/index.rst diff --git a/flytectl/doc-requirements.in b/flytectl/doc-requirements.in index cdb6725a1b..8a0e088122 100644 --- a/flytectl/doc-requirements.in +++ b/flytectl/doc-requirements.in @@ -1,3 +1,5 @@ +furo +readthedocs-sphinx-search sphinx sphinx-prompt sphinx-material diff --git a/flytectl/doc-requirements.txt b/flytectl/doc-requirements.txt index d5a288dbd0..d01f9385bf 100644 --- a/flytectl/doc-requirements.txt +++ b/flytectl/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/flytectl/docs/source/_static/custom.css b/flytectl/docs/source/_static/custom.css new file mode 100644 index 0000000000..786fcd2611 --- /dev/null +++ b/flytectl/docs/source/_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/flytectl/docs/source/_templates/sidebar/brand.html b/flytectl/docs/source/_templates/sidebar/brand.html new file mode 100644 index 0000000000..a170d6c6d1 --- /dev/null +++ b/flytectl/docs/source/_templates/sidebar/brand.html @@ -0,0 +1,18 @@ + diff --git a/flytectl/docs/source/conf.py b/flytectl/docs/source/conf.py index c346003f67..a5b237ba3f 100644 --- a/flytectl/docs/source/conf.py +++ b/flytectl/docs/source/conf.py @@ -41,6 +41,7 @@ "sphinx.ext.coverage", "sphinx-prompt", "sphinx_copybutton", + "sphinx_search.extension", ] # build the templated autosummary files @@ -73,48 +74,50 @@ # 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 = "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 = "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/flytectl", - # 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/flytectl/docs/source/index.rst b/flytectl/docs/source/index.rst index 9833bf0c50..a950c89fc9 100644 --- a/flytectl/docs/source/index.rst +++ b/flytectl/docs/source/index.rst @@ -1,22 +1,22 @@ .. flytectl doc ########################################## -Welcome to ``Flytectl``'s documentation! +``Flytectl`` Reference ########################################## -Installation -============= +Install +======= Flytectl is a Golang binary and can be installed on any platform supported by -golang. To install simply copy paste the following into the command-line +golang. To install simply copy paste the following into the command-line: .. prompt:: bash curl -s https://raw.githubusercontent.com/lyft/flytectl/master/install.sh | bash -Configuration -============== +Configure +========= Flytectl allows configuring using a YAML file or pass every configuration value on command-line. The follow configuration is useful to setup. @@ -30,23 +30,32 @@ Basic Configuration endpoint: dns:///flyte.lyft.net # Change insecure flag to ensure that you use the right setting for your environment insecure: true - # Logger settings to control logger output. Useful to debug - #logger: - #show-source: true - #level: 1 + # Logger settings to control logger output. Useful to debug logger: + show-source: true + level: 1 .. toctree:: :maxdepth: 1 - :caption: Flyte Core docs + :hidden: - Flyte Documentation + Getting Started + Tutorials + reference/index + Community - gen/flytectl .. toctree:: :maxdepth: 1 - :caption: Flytectl verbs + :caption: Flytectl + :hidden: + + Install and Configure + +.. toctree:: + :maxdepth: 1 + :caption: Verbs + :hidden: gen/flytectl_create gen/flytectl_get @@ -57,7 +66,8 @@ Basic Configuration .. toctree:: :maxdepth: 1 - :caption: Flytectl nouns + :caption: Nouns + :hidden: gen/flytectl_create_project gen/flytectl_create_execution @@ -74,13 +84,6 @@ Basic Configuration .. toctree:: :maxdepth: 2 :caption: Contribute + :hidden: contribute - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/flytectl/docs/source/reference/index.rst b/flytectl/docs/source/reference/index.rst new file mode 100644 index 0000000000..6b6ff34c49 --- /dev/null +++ b/flytectl/docs/source/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