diff --git a/docs/source/conf.py b/docs/source/conf.py index b37d1af9713..31b8bdaccd6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,10 +1,10 @@ # Configuration file for the Sphinx documentation builder. import os -import sys import pathlib -import yaml +import sys +import yaml sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../')) @@ -63,42 +63,45 @@ # Python methods should be presented in source code order autodoc_member_order = 'bysource' + # -- Options for HTML output def render_svg_logo(path): - with open(pathlib.Path(__file__).parent / path, "r") as f: + with open(pathlib.Path(__file__).parent / path, 'r') as f: content = f.read() return content + + # html_theme = 'sphinx_book_theme' html_theme = 'pydata_sphinx_theme' html_theme_options = { - "show_toc_level": 1, - "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly - "navbar_start": ["navbar-skypilot-logo"], - "navbar_center": ["navbar-nav"], - "navbar_end": [ - # "navbar-icon-links", + 'show_toc_level': 1, + 'navbar_align': 'left', # [left, content, right] For testing that the navbar items align properly + 'navbar_start': ['navbar-skypilot-logo'], + 'navbar_center': ['navbar-nav'], + 'navbar_end': [ + # 'navbar-icon-links', ], - "navbar_persistent": [ - "search-button-field", - "theme-switcher", + 'navbar_persistent': [ + 'search-button-field', + 'theme-switcher', ], 'logo': { 'svg': render_svg_logo('_static/SkyPilot_wide_light.svg'), }, - "use_edit_page_button": True, - "announcement": None, - "secondary_sidebar_items": [ - "page-toc", - "edit-this-page", + 'use_edit_page_button': True, + 'announcement': None, + 'secondary_sidebar_items': [ + 'page-toc', + 'edit-this-page', ], - "navigation_depth": 4, + 'navigation_depth': 4, 'pygment_light_style': 'tango', 'pygment_dark_style': 'monokai', 'primary_sidebar_end': [], - "footer_start": ["copyright"], - "footer_center": [], - "footer_end": [], + 'footer_start': ['copyright'], + 'footer_center': [], + 'footer_end': [], 'header_links_before_dropdown': 6, } @@ -110,11 +113,11 @@ def render_svg_logo(path): } html_sidebars = { - "**": ["main-sidebar"], + '**': ['main-sidebar'], } # The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". +# ' v documentation'. html_title = 'SkyPilot documentation' # -- Options for EPUB output @@ -145,10 +148,12 @@ def render_svg_logo(path): myst_heading_anchors = 7 show_sphinx = False + def add_metadata_to_page(app, pagename, templatename, context, doctree): # Add the author if it exists - if app.config.author != "unknown": - context["author"] = app.config.author + if app.config.author != 'unknown': + context['author'] = app.config.author + def setup(app): # -- To demonstrate ReadTheDocs switcher ------------------------------------- @@ -156,19 +161,22 @@ def setup(app): # so that we can test RTD-like behavior. We don't need to run it on RTD and we # don't wanted it loaded in GitHub Actions because it messes up the lighthouse # results. - if not os.environ.get("READTHEDOCS") and not os.environ.get("GITHUB_ACTIONS"): + if not os.environ.get('READTHEDOCS') and not os.environ.get( + 'GITHUB_ACTIONS'): app.add_css_file( - "https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css" + 'https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css' ) - app.add_css_file("https://assets.readthedocs.org/static/css/badge_only.css") + app.add_css_file( + 'https://assets.readthedocs.org/static/css/badge_only.css') # Create the dummy data file so we can link it # ref: https://github.com/readthedocs/readthedocs.org/blob/bc3e147770e5740314a8e8c33fec5d111c850498/readthedocs/core/static-src/core/js/doc-embed/footer.js # noqa: E501 - app.add_js_file("rtd-data.js") + app.add_js_file('rtd-data.js') app.add_js_file( - "https://assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js", + 'https://assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js', priority=501, ) - - app.connect("html-page-context", add_metadata_to_page) - app.connect("builder-inited", prepare_github_markdown.handle_markdown_in_gallery) + + app.connect('html-page-context', add_metadata_to_page) + app.connect('builder-inited', + prepare_github_markdown.handle_markdown_in_gallery) diff --git a/docs/source/prepare_github_markdown.py b/docs/source/prepare_github_markdown.py index 500e78161ae..50fc19e7ccf 100644 --- a/docs/source/prepare_github_markdown.py +++ b/docs/source/prepare_github_markdown.py @@ -1,9 +1,12 @@ -import re +# Modified from: https://github.com/ray-project/ray/blob/master/doc/source/preprocess_github_markdown.py import pathlib -from typing import Optional +import re import shutil +from typing import Optional + -def preprocess_github_markdown_file(source_path: str, dest_path: Optional[str] = None): +def preprocess_github_markdown_file(source_path: str, + dest_path: Optional[str] = None): """ Preprocesses GitHub Markdown files by: - Uncommenting all ```` comments in which opening tag is immediately @@ -19,28 +22,29 @@ def preprocess_github_markdown_file(source_path: str, dest_path: Optional[str] = If not provided, save to the same location as source_path. """ dest_path = dest_path if dest_path else source_path - with open(source_path, "r") as f: + with open(source_path, 'r') as f: text = f.read() # $UNCOMMENT - text = re.sub(r")", r"\1", text, flags=re.DOTALL) + text = re.sub(r')', r'\1', text, flags=re.DOTALL) # $REMOVE text = re.sub( - r"()(.*?)()", - r"", + r'()(.*?)()', + r'', text, flags=re.DOTALL, ) - with open(dest_path, "w") as f: + with open(dest_path, 'w') as f: f.write(text) + def handle_markdown_in_gallery(self, *args, **kwargs): - gallery_dir = pathlib.Path(__file__).parent / "_gallery_original" - processed_dir = pathlib.Path(__file__).parent / "gallery" + gallery_dir = pathlib.Path(__file__).parent / '_gallery_original' + processed_dir = pathlib.Path(__file__).parent / 'gallery' # Copy folder gallery_dir to processed_dir if processed_dir.exists(): shutil.rmtree(processed_dir) shutil.copytree(gallery_dir, processed_dir) - for file in processed_dir.glob("**/*.md"): + for file in processed_dir.glob('**/*.md'): # Preprocess the markdown file preprocess_github_markdown_file(file)