diff --git a/docs/config.yml b/docs/config.yml index 0939a6f..e4465af 100644 --- a/docs/config.yml +++ b/docs/config.yml @@ -19,7 +19,7 @@ extra: min_python_version_tag: "310" # The tag version of the minimum python version recent_python_version: "3.13" # The newest Python version known to work on all platforms docs_python_version: "3.13" # The version of Python required to build the documentation - translated: false # true hides content related to building translations. Default: false. + translated: true # false hides content related to building translations. Default: false. hide_coverage: false # true hides content related to code coverage. Default: false. macos_only: false # true hides tabbed content, and displays only macOS instructions. Default: false. alternate: @@ -53,6 +53,8 @@ theme: - toc.follow - navigation.indexes - navigation.footer + - navigation.tabs + - navigation.tabs.sticky - search.suggest - search.highlight - search.share diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 562c988..dca2323 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -1,11 +1,11 @@ -- BeeWare Docs Tools Demo section one - - [BeeWare Docs Tools Demo section one](section_one/index.md) +- Section one + - [Section one](section_one/index.md) - [Section one - page two](section_one/page_two.md) - [Section two](section_two/index.md) - [Section three](section_three/index.md) - ./section_three/* -- Shared content test bed - - [Shared content test bed](content_test_bed/index.md) +- Shared content testbed + - [Shared content testbed](content_test_bed/index.md) - How-to guides - Contribute - [Contributing](content_test_bed/how-to/contribute/index.md) diff --git a/docs/en/index.md b/docs/en/index.md index 1d72754..a34d208 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -1,4 +1,4 @@ -# BeeWare Docs Tools Demo +# Docs Tools Demo ## Theme checklist diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 184270a..e25ce25 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -58,6 +58,7 @@ subdirectories subdirectory symlinked symlinking +testbed Titlebar titlebar Triaging diff --git a/pyproject.toml b/pyproject.toml index c3d2e04..5597375 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,7 +30,7 @@ dependencies = [ "mkdocs-autorefs==1.4.3", "mkdocs-literate-nav==0.6.2", "mkdocs-macros-plugin==1.5.0", - "mkdocs-material==9.7.0", + "mkdocs-material==9.7.1", "mkdocs==1.6.1", "mkdocstrings-python==2.0.1", "pymdown-extensions==10.19.1", diff --git a/src/beeware_docs_tools/live_serve_en.py b/src/beeware_docs_tools/live_serve_en.py index a264bc7..417a470 100644 --- a/src/beeware_docs_tools/live_serve_en.py +++ b/src/beeware_docs_tools/live_serve_en.py @@ -20,6 +20,7 @@ def parse_args() -> Namespace: parser.add_argument("watch_directories", nargs="*") parser.add_argument("--strict", action="store_true") parser.add_argument("--source-code", action="append") + parser.add_argument("--port", type=int, default=8037) args = parser.parse_args() return args @@ -29,6 +30,7 @@ def serve_docs( output_path: Path, strict: bool, watch_directories: list[str], + port: int, ) -> None: serve_command = [ "python", @@ -40,6 +42,8 @@ def serve_docs( str(output_path / "mkdocs.en.yml"), "--watch", "docs", + "--dev-addr", + f"localhost:{port}", ] if strict: @@ -69,7 +73,7 @@ def main(): target_is_directory=True, ) - serve_docs(temp_md_path, args.strict, args.watch_directories) + serve_docs(temp_md_path, args.strict, args.watch_directories, args.port) if __name__ == "__main__": diff --git a/src/beeware_docs_tools/overrides/404.html b/src/beeware_docs_tools/overrides/404.html index 1b485d3..c860f67 100644 --- a/src/beeware_docs_tools/overrides/404.html +++ b/src/beeware_docs_tools/overrides/404.html @@ -30,10 +30,10 @@

404: Page not found

- Brutus the bee flying along with a dashed trail behind him -
-
- Brutus the bee flying along with a dashed trail behind him + + + +

Brutus can't find what you're looking for

diff --git a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css index 83e17e2..f4bfdee 100644 --- a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css +++ b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css @@ -4,290 +4,168 @@ src: url("../fonts/Cutive.woff2"); } -/*---------------------------------------------------- - Build BeeWare header - --------------------------------------------------- */ -.navbar { - font-family: 'Cutive', serif; - position: relative; - display: -ms-flexbox; - display: flex; - -ms-flex-wrap: wrap; - flex-wrap: wrap; - -ms-flex-align: center; - align-items: center; - -ms-flex-pack: justify; - justify-content: space-between; - padding: 15px 16px 8px 16px; - line-height: 1.5; -} - -.navbar > .container, -.navbar > .container-fluid { - display: -ms-flexbox; - display: flex; - -ms-flex-wrap: wrap; - flex-wrap: wrap; - -ms-flex-align: center; - align-items: center; - -ms-flex-pack: justify; - justify-content: space-between; +:root { + color-scheme: light dark; } -.navbar-dark .navbar-brand { - color: white; +[data-md-color-primary=indigo] { + --md-primary-fg-color: #343A40; + --md-primary-fg-color--light: #343A40; + --md-primary-fg-color--dark: #343A40; } -.navbar-dark .navbar-brand:hover, .navbar-dark .navbar-brand:focus { - color: white; +/* Disables dynamic font sizing, in favor of being able to more reliably keep */ +/* content at a 40rem width. */ +html { + font-size: unset; } -.navbar-dark .navbar-nav .nav-link { - color: rgba(255, 255, 255, 0.5); +/* The theme setting the font size on the body is an accessibility issue. */ +body { + font-size: 1rem; } -.navbar-dark .navbar-nav .nav-link:hover, .navbar-dark .navbar-nav .nav-link:focus { - color: rgba(255, 255, 255, 0.75); +/* Setting overall font size to 1rem. */ +.md-typeset { + font-size: 1rem; } -.navbar-dark .navbar-nav .nav-link.disabled { - color: rgba(255, 255, 255, 0.25); +/* Remove header markers to avoid spacing issues with longer headers. Use the ToC instead. */ +.md-typeset .headerlink { + display: none; } -.navbar-dark .navbar-nav .show > .nav-link, -.navbar-dark .navbar-nav .active > .nav-link, -.navbar-dark .navbar-nav .nav-link.show, -.navbar-dark .navbar-nav .nav-link.active { - color: white; +/* Disable header shadow */ +.md-header--shadow { + box-shadow: unset; } -.navbar-dark .navbar-toggler { - color: rgba(255, 255, 255, 0.5); - border-color: rgba(255, 255, 255, 0.1); +.md-header__topic, nav.md-tabs { + font-family: Cutive, serif; } -.navbar-dark .navbar-toggler-icon { - background-image: url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 30 30' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(255, 255, 255, 0.5)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 7h22M4 15h22M4 23h22'/%3E%3C/svg%3E"); +nav.md-tabs, .md-header { + background-color: var(--md-primary-fg-color); } -.navbar-dark .navbar-text { - color: rgba(255, 255, 255, 0.5); +.md-header__title { + font-size: 1.24rem; + line-height: 3.3rem; + height: 3.3rem; } -.navbar-dark .navbar-text a { - color: white; +.md-tabs__link { + font-size: 0.97rem; + margin-top: 0.7rem; } -.navbar-dark .navbar-text a:hover, .navbar-dark .navbar-text a:focus { - color: white; +.md-header__button.md-logo img { + height: 2rem; } -.bg-dark { - background-color: #343a40 !important; +.md-header { + position: unset; + display: flex; } -@media (max-width: 862.99px) { - .navbar-collapse li { - border-bottom: 1px solid #666; - padding: 8px 16px 6.4px; - } - - .navbar { - padding: 0 !important; - } - - .navbar-brand-block { - position: absolute; - margin-top: -40px; - padding: 1px 14px 2px; - right: 10px; - } - - .nav-top { - margin: 16px 14px; - } - - .navbar-collapse { - background-color: #343a40; - padding-top: 12px; - } - - .navbar-collapse .header-button li.nav-item { - border-bottom: 0 - } - - .navbar-collapse .header-button { - border-bottom: 1px solid #666; - } - - .navbar-expand-md > .container, - .navbar-expand-md > .container-fluid { - padding-right: 0; - padding-left: 0; - } +.md-header__inner { + margin-left: 0; } -@media (min-width: 863px) { - .navbar-expand-md { - -ms-flex-flow: row nowrap; - flex-flow: row nowrap; - -ms-flex-pack: start; - justify-content: flex-start; - } - - .navbar-expand-md .navbar-nav { - -ms-flex-direction: row; - flex-direction: row; - font-size: 16px; - padding-left: 14px; - } - - .navbar-expand-md .navbar-nav .dropdown-menu { - position: absolute; - } - - .navbar-expand-md .navbar-nav .nav-link { - padding-right: 8px; - padding-left: 8px; - } - - .navbar-expand-md > .container, - .navbar-expand-md > .container-fluid { - -ms-flex-wrap: nowrap; - flex-wrap: nowrap; - } - - .navbar-expand-md .navbar-collapse { - display: -ms-flexbox !important; - display: flex !important; - -ms-flex-preferred-size: auto; - flex-basis: auto; - height: 42.9px; - } - - .navbar-expand-md .navbar-toggler { - display: none; - } - - .navbar-brand-block { - padding-top: 2px; - } - - /* Search and header light-dark mode button are too low by default on wide screen */ - .md-search, .md-header__button[for="__search"] { - margin-top: -7.2px; - } +.md-header__option > input { + bottom: unset; } -.fixed-top { - position: relative; - top: 0; - right: 0; - left: 0; - z-index: 1030; +[dir="ltr"] .md-header__title { + margin-left: 0; } -.navbar-toggler { - padding: 4px 12px 4px 12px; - font-size: 16px; - line-height: 1; - background-color: transparent; - border: 1px solid transparent; - border-radius: 4px; - margin-left: 2px; +.md-header__topic { + position: unset; + transition: unset; } -.navbar-toggler:hover, .navbar-toggler:focus { - text-decoration: none; +.md-icon svg { + height: 1.65rem; + width: 1.65rem; } -.navbar-toggler:not(:disabled):not(.disabled) { - cursor: pointer; +/* Search */ +.md-search { + margin-left: 1rem; } -.navbar-toggler-icon { - display: inline-block; - width: 30px; - height: 30px; - vertical-align: middle; - content: ""; - background: no-repeat center center; - background-size: 100% 100%; +input.md-search__input, +.md-search__suggest, +.md-search-result__meta { + font-family: 'Cutive', serif; } -.navbar-brand { - display: inline-block; - padding: 3px 2px 5px 0; - font-size: 20px; - line-height: inherit; - white-space: nowrap; - text-decoration: none; +input.md-search__input, +.md-search__suggest { + font-size: 1.21rem; } -.navbar-brand:hover, .navbar-brand:focus { - text-decoration: none; +.md-search-result__meta { + padding: 1rem 0.8rem 0.4rem 0.8rem; + line-height: 2rem; + font-size: 0.88rem; } -.navbar-brand img { - max-width: initial; - margin-right: 8px; - margin-left: 8px; - vertical-align: middle; +.md-search__form { + height: 2.5rem; } -.navbar-collapse { - -ms-flex-preferred-size: 100%; - flex-basis: 100%; - -ms-flex-positive: 1; - flex-grow: 1; - -ms-flex-align: center; - align-items: center; +@media screen and (min-width: 60em) { + .md-search__inner { + width: unset; + } } -.navbar-nav { - display: -ms-flexbox; - display: flex; - -ms-flex-direction: column; - flex-direction: column; - padding-left: 0; +/* Cleans up vertical spacing on breadcrumbs. */ +.md-path { margin-top: 0; - margin-bottom: 3px; - list-style: none; + padding-top: 0; + font-size: 1rem; } -.navbar-nav .nav-link { - padding-right: 0; - padding-left: 0; - text-decoration: none; +@media screen and (min-width: 76.25em) { + .md-path { + flex: 54%; + margin-right: 2.5rem; + margin: 0 0.8rem; + } } -.navbar-nav .dropdown-menu { - position: static; - float: none; +/* Forces all titles to line up, including pages without breadcrumbs. */ +.md-path__list { + margin-top: 1.5rem; } -.mr-auto, -.mx-auto { - margin-right: auto; +.md-path__item { + margin-top: -0.8rem; } -.collapse:not(.show) { - display: none; +/* Link colors */ +/* Remove link color from section headers that are not links */ +.md-nav__link[for]:focus, +.md-nav__link[for]:hover { + color: unset; } -/*---------------------------------------------------- - Material CSS overrides - --------------------------------------------------- */ -:root { - color-scheme: light dark; +/* Only color section header links as links */ +.md-typeset a, +a.md-nav__link, +a.md-nav__link[for]:focus, +a.md-nav__link[for]:hover { + color: light-dark(#084AFF, #526CFE); } -[data-md-color-primary=indigo] { - --md-primary-fg-color: #343A40; - --md-primary-fg-color--light: #343A40; - --md-primary-fg-color--dark: #343A40; +.md-nav__item a.md-nav__link--active { + color: light-dark(#30314B, #96ACEE) } +/* Header fonts */ .md-typeset h1, .md-typeset h2, .md-typeset h3, @@ -296,11 +174,45 @@ .md-typeset h6 { font-family: 'Cutive', serif; color: var(--md-typeset-color); + clear: both; } -/* Fix issue with spacing when title is exactly the width of the article column */ -.md-typeset h1 a.headerlink { - display: none; +/* Update font sizes to match sizes before dynamic sizing was disabled. */ +/* Headers */ +.md-typeset h1 { + font-size: 3rem; + margin-bottom: 0.64rem; +} + +.md-typeset h2 { + font-size: 2.35rem; + margin-bottom: 0.64rem; + margin-top: 2rem; +} + +.md-typeset h3 { + font-size: 1.6rem; + margin: 2rem 0 0 0; +} + +.md-typeset h4 { + font-size: 1.2rem; +} + +.md-typeset h5, +.md-typeset h6 { + font-size: 0.96rem; +} + +/* Admonitions */ +.md-typeset .admonition, +.md-typeset details { + font-size: 1rem; +} + +/* Tabs */ +.md-typeset .tabbed-labels > label { + font-size: 1rem; } /* Link colors */ @@ -321,19 +233,8 @@ a.md-nav__link[for]:hover { color: light-dark(#30314B, #96ACEE) } -/* Unsticky header, add margin to deal with sidebar top margin changes */ -.md-header { - position: unset; -} - -/* Disable header shadow */ -.md-header--shadow { - box-shadow: unset; -} - -/* Force admonitions to render at the same font size as the rest of the content */ -.md-typeset .admonition { - font-size: unset; +.md-main__inner { + margin-top: unset; } /* Sidebar title and GitHub links font and color */ @@ -345,13 +246,6 @@ a.md-nav__link[for]:hover { color: unset; } -.md-select:focus-within .md-select__inner, -.md-select:hover .md-select__inner, -.md-select__inner, -.md-select__list { - max-height: none; -} - /* Version number */ .version-number { overflow-wrap: anywhere; @@ -408,21 +302,17 @@ a.md-nav__link[for]:hover { margin-right: 0.2rem; } -.small .site-name { - font-size: 24px; -} - /* Embiggen homepage logo */ .md-nav__title .md-nav__button.md-logo img { height: unset; } /* Embiggen sidebar drawer logo and match sidebar */ -.md-nav__title.small .md-nav__button.md-logo img { - height: unset; - max-width: unset; - width: 74px; -} +/*.md-nav__title.small .md-nav__button.md-logo img {*/ +/* height: unset;*/ +/* max-width: unset;*/ +/* width: 74px;*/ +/*}*/ /* The menu button for the sidebar drawer to display the sidebar on smaller displays */ .mobile-drawer-button-site-name { @@ -475,6 +365,10 @@ and (min-width: 1220px) { .site-name { font-size: 19px; } + + .sidebar-logo { + width: 50px; + } } @media screen and (max-width: 1999.99px) @@ -482,6 +376,10 @@ and (min-width: 1600px) { .site-name { font-size: 21px; } + + .sidebar-logo { + width: 74px; + } } @media screen and (min-width: 2000px) { @@ -526,7 +424,7 @@ and (min-width: 1600px) { } .site-name { - font-size: 24px; + font-size: 50px; } .md-nav__title .md-nav__button.md-logo img { @@ -536,10 +434,27 @@ and (min-width: 1600px) { } } -/* Setting the font size on the body is an accessibility issue, as well as interfering - with the header font size. This resolves both. */ -body { - font-size: 1rem; +/* Sidebar drawer */ +@media screen and (max-width: 76.2344em) { + [dir="ltr"] .md-sidebar--primary { + width: 12.1rem; + } + + .md-nav__title .md-nav__button.md-logo img { + width: 50px; + } + + .site-name { + font-size: 1rem; + } + + .version-number { + font-size: 0.65rem; + } + + .md-nav__link { + font-size: 1rem; + } } /* Removes padding and margins to regain screen-space on pages with short content. @@ -553,22 +468,31 @@ body { } .md-header { - margin-bottom: 72px; + margin-bottom: 49px; } .md-sidebar { padding-top: 12px; + width: 16rem; +} + +.md-grid { + max-width: 75rem; } .md-content__inner { padding-top: 8px; - margin-top: -69px; + margin-top: -54px; } .md-content__inner::before { height: 0; } +.md-nav { + font-size: 1rem; +} + .md-footer { position: relative; margin-top: 69px; @@ -576,7 +500,8 @@ body { @media screen and (min-width: 60em) { .md-sidebar__scrollwrap { - margin-top: -64px; + margin-top: -54px; + padding-bottom: 4rem; /* Scrollbar bugfix; TODO: Merge in when PR is merged */ } } @@ -616,7 +541,7 @@ readthedocs-docdiff { } /* Forces only highlighting the important bits of codeblocks */ -.highlight .gp, .highlight .go { +.highlight .gp, .highlight .go, .highlight .w { user-select: none; -webkit-user-select: none; } @@ -658,6 +583,15 @@ input.md-search__input, .md-search__suggest, .md-search-result__meta { padding-top: 1px; } +.md-search-result .md-typeset h1 { + font-size: 1.6rem; +} + +.md-search-result .md-typeset h2, +.md-search-result .md-typeset { + font-size: 1rem; +} + /* Footer and footer navigation color */ .md-footer, .md-footer-meta { background-color: light-dark(#f5f5f5, #343A40); @@ -682,17 +616,29 @@ footer.md-footer *, html .md-footer-meta.md-typeset a { } .md-footer__title { - font-size: .6rem; + font-size: 0.9rem; } .md-footer__direction { - font-size: .6rem + font-size: 0.9rem; } .md-footer__button { margin: 0 0 0.2rem 0; } +.md-copyright { + font-size: 1rem; +} + +.md-social__link svg { + max-height: 1.2rem; +} + +.footer-link { + margin: 0.1rem 0 0 0.3rem; +} + /* Indent contents of classes/methods/etc. */ .doc-contents, .doc-signature { diff --git a/src/beeware_docs_tools/overrides/blog-post.html b/src/beeware_docs_tools/overrides/blog-post.html new file mode 100644 index 0000000..70a7279 --- /dev/null +++ b/src/beeware_docs_tools/overrides/blog-post.html @@ -0,0 +1,205 @@ + + +{% extends "main.html" %} + +{% import "partials/nav-item.html" as item with context %} + + +{% block container %} +
+ + +
+
+
+ + + + {% if "toc.integrate" in features %} + {% include "partials/toc.html" %} + {% endif %} +
+
+
+ + +
+ {% block content %} + {% include "partials/content.html" %} + {% endblock %} +
+
+{% endblock %} diff --git a/src/beeware_docs_tools/overrides/partials/header.html b/src/beeware_docs_tools/overrides/partials/header.html index 250c25c..6fb2e1b 100644 --- a/src/beeware_docs_tools/overrides/partials/header.html +++ b/src/beeware_docs_tools/overrides/partials/header.html @@ -1,47 +1,138 @@ -
+ +{% import "partials/tabs-item.html" as item with context %} + +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} + + +
+ + + {% if config.theme.palette %} + {% if not config.theme.palette is mapping %} {% include "partials/palette.html" %} + {% endif %} + {% endif %} - {% include "partials/javascripts/palette.html" %} -
+ {% if not config.theme.palette is mapping %} + {% include "partials/javascripts/palette.html" %} + {% endif %} {% if config.extra.alternate %} {% include "partials/alternate.html" %} {% endif %} + {% if "material/search" in config.plugins %} {% set search = config.plugins["material/search"] | attr("config") %} @@ -57,19 +148,5 @@ {% include "partials/search.html" %} {% endif %} {% endif %} - - -
- - -
- {{ config.site_name }} -
-
- {{ config.extra.version }} -
-
+ diff --git a/src/beeware_docs_tools/overrides/partials/nav.html b/src/beeware_docs_tools/overrides/partials/nav.html index 46086db..ce65191 100644 --- a/src/beeware_docs_tools/overrides/partials/nav.html +++ b/src/beeware_docs_tools/overrides/partials/nav.html @@ -57,6 +57,7 @@ + {% if not config.extra.hide_dev_links %}
@@ -69,6 +70,7 @@
+ {% endif %} @@ -80,7 +82,7 @@