diff --git a/.gitignore b/.gitignore index 4626ade1e1..abaf1aa54a 100644 --- a/.gitignore +++ b/.gitignore @@ -88,6 +88,7 @@ instance/ # mkdocs vizro-core/site vizro-ai/site +Vizro-mcp/site # PyBuilder .pybuilder/ diff --git a/vizro-ai/hatch.toml b/vizro-ai/hatch.toml index 9afc90f2e7..71d9bcb99a 100644 --- a/vizro-ai/hatch.toml +++ b/vizro-ai/hatch.toml @@ -62,8 +62,7 @@ test-unit-coverage = [ [envs.docs] dependencies = [ - "mkdocs>=1.6", - "mkdocs-material", + "zensical", "mkdocs-git-revision-date-localized-plugin>=1.2.5", "mkdocstrings[python]", "linkchecker", @@ -75,14 +74,14 @@ detached = true installer = "uv" [envs.docs.scripts] -build = "mkdocs build --strict" +build = "zensical build --clean" # Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify # more advanced settings using a linkcheckerrc config file. openai.com doesn't seem to work well with linkchecking, # throwing 403 errors, but these are not real errors. link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://vizro.readthedocs.io/ --ignore-url=https://platform.openai.com/docs/models --ignore-url=openai.com --ignore-url=https://openai.com/" pip = '"{env:HATCH_UV}" pip {args}' pycafe-links = "../tools/pycafe/docs_links_filtering.sh" -serve = "mkdocs serve --open" +serve = "zensical serve --open {args}" [envs.lower-bounds] extra-dependencies = ["pydantic==2.11.9"] # required by langchain>=0.3.0 and openai>=1.108.0 diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index 7528950504..ad334540a6 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -1,5 +1,7 @@ site_name: Vizro-AI site_url: https://vizro.readthedocs.io/projects/vizro-ai +site_dir: site +docs_dir: docs nav: - Vizro-AI: index.md - Tutorials: @@ -39,9 +41,17 @@ repo_name: mckinsey/vizro-ai theme: name: material + variant: classic language: en palette: - scheme: default + toggle: + icon: lucide/sun + name: Switch to dark mode + - scheme: slate + toggle: + icon: lucide/moon + name: Switch to light mode font: text: Google sans code: Source Code Pro @@ -122,8 +132,7 @@ hooks: extra_css: - stylesheets/extra.css -# Strictest settings possible, and will be elevated to ERROR when run with --strict. -# See https://www.mkdocs.org/user-guide/configuration/#validation. +# Keep these for now as strict building will be enabled by Zensical soon validation: omitted_files: warn absolute_links: warn diff --git a/vizro-core/docs/pages/user-guides/custom-components.md b/vizro-core/docs/pages/user-guides/custom-components.md index 00c935b274..ab92cd6192 100644 --- a/vizro-core/docs/pages/user-guides/custom-components.md +++ b/vizro-core/docs/pages/user-guides/custom-components.md @@ -156,7 +156,7 @@ vm.Parameter.add_type("selector", TooltipNonCrossRangeSlider) You may want to use this strategy to: -- Create a new component that does not exist as a [built-ninVizro model][vizro.models]. +- Create a new component that does not exist as a [built-in Vizro model][vizro.models]. - Make extensive changes to an existing component. - Combine multiple components into a single higher-level component, similar to a Dash [All-in-One component](https://dash.plotly.com/all-in-one-components). diff --git a/vizro-core/docs/stylesheets/favicon.png b/vizro-core/docs/stylesheets/favicon.png new file mode 100644 index 0000000000..d7c4680712 Binary files /dev/null and b/vizro-core/docs/stylesheets/favicon.png differ diff --git a/vizro-core/hatch.toml b/vizro-core/hatch.toml index 8ddf5205a2..9244121eba 100644 --- a/vizro-core/hatch.toml +++ b/vizro-core/hatch.toml @@ -115,15 +115,12 @@ test-unit-coverage = [ [envs.docs] dependencies = [ - "mkdocs>=1.6", - "mkdocs-material", + "zensical", "mkdocs-git-revision-date-localized-plugin>=1.2.5", "mkdocstrings[python]", "griffe-warnings-deprecated", - "mkdocs-llmstxt-md", "mkdocs-llmstxt>=0.5.0", "linkchecker", - "mkdocs-open-in-new-tab", "mkdocs-pycafe", "PyGithub", "playwright" @@ -132,7 +129,7 @@ installer = "uv" template = "docs" # Can't be detached = true since griffe_extensions:DynamicallyInspect needs vizro to be importable. [envs.docs.scripts] -build = "mkdocs build --strict" +build = "zensical build --clean" # Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify # more advanced settings using a linkcheckerrc config file. link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://vizro.readthedocs.io/ --ignore-url=https://platform.ploomber.io/register --ignore-url=https://huggingface.co/join --ignore-url=https://www.ag-grid.com/" @@ -140,7 +137,7 @@ link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html -- logo-check = "grep -q 'logo_watermark_extended.svg' docs/pages/user-guides/install.md" pip = '"{env:HATCH_UV}" pip {args}' pycafe-links = "../tools/pycafe/docs_links_filtering.sh" -serve = "mkdocs serve --open {args}" +serve = "zensical serve --open {args}" [envs.examples] # TODO: once the visual-vocabulary dashboard has moved out of this repo, this environment should be removed fully and diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index 3080c62152..5569a3ddf5 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -1,7 +1,12 @@ site_name: Vizro site_url: https://vizro.readthedocs.io/en/stable/ +site_description: Core Vizro documentation +site_dir: site +docs_dir: docs +use_directory_urls: true + +# Make sure any new page added here is also added to the llmstxt plugin below nav: - # Make sure any new page added here is also added to the llmstxt plugin below (around line 156) - Vizro: index.md - Tutorials: - Quickstart tutorial: pages/tutorials/quickstart-tutorial.md @@ -79,14 +84,25 @@ theme: name: material language: en custom_dir: docs/overrides + variant: classic + favicon: assets/images/favicon.png palette: - scheme: default + toggle: + icon: lucide/sun + name: Switch to dark mode + - scheme: slate + toggle: + icon: lucide/moon + name: Switch to light mode font: text: Google sans code: Source Code Pro icon: repo: fontawesome/brands/github features: + - header.autohide + - navigation.path - navigation.expand - navigation.instant - navigation.indexes @@ -100,9 +116,6 @@ theme: - content.code.copy - content.code.annotate -watch: - - src - markdown_extensions: - pymdownx.highlight: anchor_linenums: true @@ -133,14 +146,14 @@ markdown_extensions: - md_in_html - attr_list - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:zensical.extensions.emoji.twemoji + emoji_generator: !!python/name:zensical.extensions.emoji.to_svg plugins: - search - autorefs - - llmstxt: # https://pypi.org/project/mkdocs-llmstxt/ - markdown_description: + - llmstxt: + markdown_description: | Vizro is an open-source Python-based toolkit to build data visualization apps. Every Vizro app is defined by a simple configuration, using the high-level categories @@ -214,12 +227,11 @@ plugins: python: options: show_bases: false - show_source: false #currently doesn't show source at correct level, and not for pydantic models + show_source: false docstring_style: google merge_init_into_class: true docstring_section_style: list separate_signature: true - # filters: ["!^_"] show_root_heading: true docstring_options: ignore_init_summary: true @@ -241,9 +253,9 @@ extra: - name: google-site-verification content: "CYb3cxosCgsN2QDQVaSGQpMQCesqpsGQ3oTM02NtvkY" extra_css: - - stylesheets/extra.css + - /stylesheets/extra.css extra_javascript: - - javascripts/extra.js + - /javascripts/extra.js # Strictest settings possible, and will be elevated to ERROR when run with --strict. # See https://www.mkdocs.org/user-guide/configuration/#validation. validation: diff --git a/vizro-core/zensical.toml.backup b/vizro-core/zensical.toml.backup new file mode 100644 index 0000000000..1a3d42d689 --- /dev/null +++ b/vizro-core/zensical.toml.backup @@ -0,0 +1,307 @@ +[project] +docs_dir = "docs" +extra_css = ["/stylesheets/extra.css"] +extra_javascript = ["/javascripts/extra.js"] +# Make sure any new page added here is also added to the llmstxt plugin below (around line 170) +nav = [ + {"Vizro" = "index.md"}, + {"Tutorials" = [ + {"Quickstart tutorial" = "pages/tutorials/quickstart-tutorial.md"}, + {"Explore Vizro" = "pages/tutorials/explore-components.md"}, + {"Write your own actions" = "pages/tutorials/custom-actions-tutorial.md"} + ]}, + {"How-to guides" = [ + {"Fundamentals" = [ + {"Install Vizro" = "pages/user-guides/install.md"}, + {"Dashboard" = "pages/user-guides/dashboard.md"}, + {"Page" = "pages/user-guides/pages.md"}, + {"Run or deploy dashboards" = "pages/user-guides/run-deploy.md"} + ]}, + {"Components" = [ + {"Overview" = "pages/user-guides/components.md"}, + {"Graph" = "pages/user-guides/graph.md"}, + {"Table" = "pages/user-guides/table.md"}, + {"Figure" = "pages/user-guides/figure.md"}, + {"Card" = "pages/user-guides/card.md"}, + {"Text" = "pages/user-guides/text.md"}, + {"Button" = "pages/user-guides/button.md"}, + {"Container" = "pages/user-guides/container.md"}, + {"Tab" = "pages/user-guides/tabs.md"} + ]}, + {"Controls" = [ + {"Overview" = "pages/user-guides/controls.md"}, + {"Filter" = "pages/user-guides/filters.md"}, + {"Parameter" = "pages/user-guides/parameters.md"}, + {"Selector" = "pages/user-guides/selectors.md"} + ]}, + {"Navigation" = "pages/user-guides/navigation.md"}, + {"Actions" = [ + {"Overview" = "pages/user-guides/actions.md"}, + {"Handle data" = "pages/user-guides/data-actions.md"}, + {"Graph and table interactions" = "pages/user-guides/graph-table-actions.md"} + ]}, + {"Visual formatting" = [ + {"Overview" = "pages/user-guides/visual-formatting.md"}, + {"Layout" = "pages/user-guides/layouts.md"}, + {"Theme" = "pages/user-guides/themes.md"}, + {"Assets" = "pages/user-guides/assets.md"}, + {"Custom CSS" = "pages/user-guides/custom-css.md"} + ]}, + {"Data" = [ + {"Overview" = "pages/user-guides/data.md"}, + {"Kedro Data Catalog" = "pages/user-guides/kedro-data-catalog.md"} + ]}, + {"Extensions" = [ + {"Overview" = "pages/user-guides/extensions.md"}, + {"Custom actions" = "pages/user-guides/custom-actions.md"}, + {"Custom charts" = "pages/user-guides/custom-charts.md"}, + {"Custom tables" = "pages/user-guides/custom-tables.md"}, + {"Custom figures" = "pages/user-guides/custom-figures.md"}, + {"Custom components" = "pages/user-guides/custom-components.md"} + ]} + ]}, + {"API reference" = [ + {"Vizro" = "pages/API-reference/vizro.md"}, + {"Models" = "pages/API-reference/models.md"}, + {"Actions" = "pages/API-reference/actions.md"}, + {"Table functions" = "pages/API-reference/table-callables.md"}, + {"Figure functions" = "pages/API-reference/figure-callables.md"}, + {"Kedro integration" = "pages/API-reference/kedro-integration.md"}, + {"Deprecations" = "pages/API-reference/deprecations.md"} + ]}, + {"Find out more" = [ + {"Technical" = [ + {"Vizro schema" = "pages/explanation/schema.md"}, + {"Actions" = "pages/explanation/actions-explanation.md"} + ]}, + {"About Vizro" = [ + {"FAQs" = "pages/explanation/faq.md"}, + {"User examples" = "pages/explanation/your-examples.md"}, + {"Cheatsheet" = "pages/cheatsheet/cheatsheet.html"}, + {"Contribute to Vizro" = "pages/explanation/contributing.md"}, + {"Documentation style" = "pages/explanation/documentation-style-guide.md"}, + {"Authors" = "pages/explanation/authors.md"} + ]} + ]}, + {"Vizro-MCP" = [ + {"Vizro-MCP" = "https://vizro.readthedocs.io/projects/vizro-mcp/"} + ]} +] +repo_name = "mckinsey/vizro" +repo_url = "https://github.com/mckinsey/vizro" +site_description = "Core Vizro documentation" +site_dir = "site" +site_name = "Vizro" +site_url = "https://vizro.readthedocs.io/en/stable/" +use_directory_urls = true + +[[project.extra.meta]] +content = "CYb3cxosCgsN2QDQVaSGQpMQCesqpsGQ3oTM02NtvkY" +name = "google-site-verification" + +[project.markdown_extensions.admonition] + +[project.markdown_extensions.attr_list] + +[project.markdown_extensions.footnotes] + +[project.markdown_extensions.md_in_html] + +[project.markdown_extensions.pymdownx.arithmatex] +generic = true + +[project.markdown_extensions.pymdownx.details] + +[project.markdown_extensions.pymdownx.emoji] +emoji_generator = "zensical.extensions.emoji.to_svg" +emoji_index = "zensical.extensions.emoji.twemoji" + +[project.markdown_extensions.pymdownx.highlight] +anchor_linenums = true + +[project.markdown_extensions.pymdownx.inlinehilite] + +[project.markdown_extensions.pymdownx.keys] + +[project.markdown_extensions.pymdownx.mark] + +[project.markdown_extensions.pymdownx.snippets] + +[project.markdown_extensions.pymdownx.superfences] + +[[project.markdown_extensions.pymdownx.superfences.custom_fences]] +class = "mermaid" +format = "pymdownx.superfences.fence_code_format" +name = "mermaid" + +[[project.markdown_extensions.pymdownx.superfences.custom_fences]] +class = "highlight" +format = "mkdocs_pycafe.formatter" +kwds = {type = "vizro", requirements = "vizro==0.1.49"} +name = "python" +validator = "mkdocs_pycafe.validator" + +[project.markdown_extensions.pymdownx.tabbed] +alternate_style = true + +[project.plugins.autorefs] + +[project.plugins.git-revision-date-localized] +enable_creation_date = false + +[project.plugins.llmstxt] # https://pypi.org/project/mkdocs-llmstxt/ +base_url = "https://vizro.readthedocs.io/en/0.1.49/" +full_output = "llms-full.txt" +markdown_description = """ +Vizro is an open-source Python-based toolkit to build data visualization apps. + +Every Vizro app is defined by a simple configuration, using the high-level categories +* Components (charts, tables, cards, KPI indicators, forms and more), +* Controls (filters and parameters, using a range of selectors such as drop-down menus and sliders), +* Actions (interactions between components, drill-throughs, export functionality and more), +* Layouts (grid layouts or flexible containers, with a range of pre-set styles), +* Navigation (a range of app layout and navigation settings, including nested page hierarchies). + +Configuration can be written in multiple formats including Pydantic models, JSON, YAML or Python dictionaries for added flexibility of implementation. + +Optional high-code extensions enable almost infinite customization in a modular way, combining the best of low-code and high-code - including bespoke visual formatting and custom components. +""" + +[project.plugins.llmstxt.sections] +ACTIONS = [ + {"pages/user-guides/actions.md" = "Actions"}, + {"pages/user-guides/data-actions.md" = "Handle data"}, + {"pages/user-guides/graph-table-actions.md" = "Graph and table interactions"} +] +"ADD CONTROLS TO A DASHBOARD" = [ + {"pages/user-guides/controls.md" = "Controls overview"}, + {"pages/user-guides/filters.md" = "Filters"}, + {"pages/user-guides/parameters.md" = "Parameters"}, + {"pages/user-guides/selectors.md" = "Selectors"} +] +"DASHBOARD NAVIGATION ELEMENTS" = [ + {"pages/user-guides/navigation.md" = "Navigation"} +] +"EXTEND THE DASHBOARD WITH CUSTOMIZATIONS" = [ + {"pages/user-guides/extensions.md" = "Extensions overview"}, + {"pages/user-guides/custom-charts.md" = "Custom charts"}, + {"pages/user-guides/custom-tables.md" = "Custom tables"}, + {"pages/user-guides/custom-components.md" = "Custom components"}, + {"pages/user-guides/custom-actions.md" = "Custom actions"}, + {"pages/user-guides/custom-figures.md" = "Custom figures"} +] +"FAQS, EXAMPLES, CONTRIBUTION GUIDANCE AND THE VIZRO SCHEMA" = [ + {"pages/explanation/faq.md" = "FAQs"}, + {"pages/explanation/your-examples.md" = "Examples created by the Vizro community"}, + {"pages/explanation/contributing.md" = "How to contribute to Vizro's open source project"}, + {"pages/explanation/documentation-style-guide.md" = "Documentation style guide"}, + {"pages/explanation/schema.md" = "The Vizro schema"}, + {"pages/explanation/authors.md" = "Vizro contributor listing"} +] +"FUNDAMENTAL CONCEPTS IN VIZRO" = [ + {"pages/user-guides/install.md" = "Guide on how to install Vizro"}, + {"pages/user-guides/dashboard.md" = "Dashboard basics"}, + {"pages/user-guides/pages.md" = "Pages"}, + {"pages/user-guides/run-deploy.md" = "How to run or deploy dashboards"} +] +"HOW TO APPLY VISUAL FORMATTING" = [ + {"pages/user-guides/visual-formatting.md" = "Formatting overview"}, + {"pages/user-guides/layouts.md" = "Layouts"}, + {"pages/user-guides/themes.md" = "Themes"}, + {"pages/user-guides/assets.md" = "Assets"}, + {"pages/user-guides/custom-css.md" = "Custom CSS"} +] +"LEARN ABOUT VIZRO COMPONENTS" = [ + {"pages/user-guides/components.md" = "Components overview"}, + {"pages/user-guides/graph.md" = "Graphs"}, + {"pages/user-guides/table.md" = "Tables"}, + {"pages/user-guides/figure.md" = "Figures"}, + {"pages/user-guides/card.md" = "Cards"}, + {"pages/user-guides/text.md" = "Text"}, + {"pages/user-guides/button.md" = "Buttons"}, + {"pages/user-guides/container.md" = "Containers"}, + {"pages/user-guides/tabs.md" = "Tabs"} +] +"MANAGE DATA USED BY THE DASHBOARD" = [ + {"pages/user-guides/data.md" = "Data"}, + {"pages/user-guides/kedro-data-catalog.md" = "Kedro Data Catalog"} +] +TUTORIALS = [ + {"pages/tutorials/quickstart-tutorial.md" = "A quickstart dashboard tutorial"}, + {"pages/tutorials/explore-components.md" = "An in-depth tutorial to introduce Vizro's key features (accompanying Video is available)"} +] + +# ------------------------- +# mkdocs plugin +# ------------------------- +[project.plugins.mkdocstrings] + +[project.plugins.mkdocstrings.handlers.python] +paths = ["src"] + +[project.plugins.mkdocstrings.handlers.python.options] +docstring_section_style = "list" +docstring_style = "google" +extensions = [ + {"docs/griffe_extensions.py" = {paths = ["vizro.figures.kpi_card", "vizro.figures.kpi_card_reference"]}}, + {griffe_warnings_deprecated = {kind = "danger", title = "Deprecated"}} +] +merge_init_into_class = true +separate_signature = true +show_bases = false +show_root_heading = true +show_source = false + +[project.plugins.mkdocstrings.handlers.python.options.docstring_options] +ignore_init_summary = true +returns_named_value = false +warn_unknown_params = false + +[project.plugins.search] + +# ------------------------- +[project.theme] +custom_dir = "docs/overrides" +favicon = "assets/images/favicon.png" +features = [ + "header.autohide", + "navigation.path", + "navigation.expand", + "navigation.instant", + "navigation.indexes", + "navigation.tabs", + "navigation.tabs.sticky", + "navigation.tracking", + "search.suggest", + "search.highlight", + "content.tabs.link", + "content.code.annotation", + "content.code.copy", + "content.code.annotate" +] +language = "en" +variant = "classic" + +[project.theme.font] +code = "Source Code Pro" +text = "Google sans" + +[project.theme.icon] +repo = "fontawesome/brands/github" + +[[project.theme.palette]] +scheme = "default" +toggle.icon = "lucide/sun" +toggle.name = "Switch to dark mode" + +[[project.theme.palette]] +scheme = "slate" +toggle.icon = "lucide/moon" +toggle.name = "Switch to light mode" + +# Keep these for now as strict building will be enabled by Zensical soon +# validation: +# omitted_files: warn +# absolute_links: warn +# unrecognized_links: warn +# anchors: warn diff --git a/vizro-mcp/hatch.toml b/vizro-mcp/hatch.toml index 78a797b054..9e5556b6b3 100644 --- a/vizro-mcp/hatch.toml +++ b/vizro-mcp/hatch.toml @@ -40,8 +40,7 @@ test-unit-coverage = [ [envs.docs] dependencies = [ - "mkdocs>=1.6", - "mkdocs-material", + "zensical", "mkdocs-git-revision-date-localized-plugin>=1.2.5", "mkdocstrings[python]", "linkchecker", @@ -53,7 +52,7 @@ detached = true installer = "uv" [envs.docs.scripts] -build = "mkdocs build --strict" +build = "zensical build --clean" # Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify # more advanced settings using a linkcheckerrc config file. openai.com doesn't seem to work well with linkchecking, # throwing 403 errors, but these are not real errors. @@ -77,7 +76,7 @@ python ../tools/check_vizro_docs_links_in_mcp_prompts.py ''' pip = '"{env:HATCH_UV}" pip {args}' pycafe-links = "../tools/pycafe/docs_links_filtering.sh" -serve = "mkdocs serve --open" +serve = "zensical serve --open {args}" [publish.index] disable = true diff --git a/vizro-mcp/mkdocs.yml b/vizro-mcp/mkdocs.yml index 19af38196f..aec355b494 100644 --- a/vizro-mcp/mkdocs.yml +++ b/vizro-mcp/mkdocs.yml @@ -1,5 +1,14 @@ site_name: Vizro-MCP site_url: https://vizro.readthedocs.io/projects/vizro-mcp +site_description: Vizro-MCP documentation +site_dir: site +docs_dir: docs +# This infers the version number of the latest release of whole repo, so we're hiding it for sub-packed in extra.css +repo_url: https://github.com/mckinsey/vizro/tree/main/vizro-mcp +repo_name: mckinsey/vizro-mcp + +use_directory_urls: true + nav: - Vizro-MCP: index.md - Get started: @@ -25,25 +34,32 @@ nav: - Vizro: https://vizro.readthedocs.io - Vizro-AI: https://vizro.readthedocs.io/projects/vizro-ai/ -# This infers the version number of the latest release of whole repo, so we're hiding it for sub-packed in extra.css -repo_url: https://github.com/mckinsey/vizro/tree/main/vizro-mcp -repo_name: mckinsey/vizro-mcp - theme: name: material + variant: classic language: en palette: - scheme: default + toggle: + icon: lucide/sun + name: Switch to dark mode + - scheme: slate + toggle: + icon: lucide/moon + name: Switch to light mode font: text: Google sans code: Source Code Pro icon: repo: fontawesome/brands/github features: + - header.autohide + - navigation.path + - navigation.expand - navigation.instant + - navigation.indexes - navigation.tabs - navigation.tabs.sticky - - navigation.sections - navigation.tracking - search.suggest - search.highlight @@ -113,8 +129,7 @@ plugins: extra_css: - stylesheets/extra.css -# Strictest settings possible, and will be elevated to ERROR when run with --strict. -# See https://www.mkdocs.org/user-guide/configuration/#validation. +# Keep these for now as strict building will be enabled by Zensical soon validation: omitted_files: warn absolute_links: warn