diff --git a/README.md b/README.md index 2bf36b2..c775ce6 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Follow the steps below to build and view the site locally. ## Requirements * [Node.js] >= 16 to be able to [view the output](#viewing-the-output) -* python3 +* python3 >= 3.10 * python3-venv * [Task] diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..6be4ce5 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,21 @@ +html[data-theme="dark"], html[data-theme="light"] { + --pst-color-primary: #3399ff; + --pst-color-secondary: #9580ff; +} + +a { + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +/* +Remove margin from sidebar-primary-items__end so that we don't have an unnecessary scrollbar. We're +not using the end items currently. +*/ +.bd-sidebar-primary .sidebar-primary-items__end { + margin-top: 0; + margin-bottom: 0; +} diff --git a/docs/conf.py b/docs/conf.py index f619d29..1b79ea0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,6 +7,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "YScope" +# NOTE: We don't include a period after "Inc" since the theme adds one already. +project_copyright = "2023-2024 YScope Inc" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -16,20 +18,49 @@ "sphinx_design" ] -templates_path = ["_templates"] -exclude_patterns = [] +# -- MyST extensions ----------------------------------------------------------- +# https://myst-parser.readthedocs.io/en/stable/syntax/optional.html +myst_enable_extensions = [ + "colon_fence", +] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_favicon = "_static/favicon.ico" html_title = "YScope Docs" -html_show_copyright = False +html_show_copyright = True + html_static_path = ["_static"] -html_theme = "furo" +html_theme = "pydata_sphinx_theme" + +# -- Theme options ------------------------------------------------------------ +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html + html_theme_options = { - "source_repository": "https://github.com/y-scope/yscope-docs/", - "source_branch": "main", - "source_directory": "docs", + "footer_start": ["copyright"], + "footer_center": [], + "footer_end": ["theme-version"], + "primary_sidebar_end": [], + "secondary_sidebar_items": ["page-toc", "edit-this-page"], + "show_prev_next": False, + "use_edit_page_button": True, +} + +# -- Theme source buttons ------------------------------------------------------ +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html + +html_context = { + "github_user": "y-scope", + "github_repo": "yscope-docs", + "github_version": "main", + "doc_path": "docs", } + +# -- Theme custom CSS and JS --------------------------------------------------- +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/static_assets.html + + +def setup(app): + app.add_css_file("custom.css") diff --git a/requirements.txt b/requirements.txt index 00055e5..354d741 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -furo==2022.12.7 -myst-parser==1.0.0 -sphinx==5.3.0 -sphinx-design==0.3.0 +myst-parser>=2.0.0 +pydata-sphinx-theme>=0.15.2 +sphinx>=7.2.6 +sphinx-design>=0.5.0