From 24b665c35bec7e72a1c62ee982c4268c33b80254 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 30 Oct 2026 17:17:03 -0300 Subject: [PATCH] docs: align site theme and structure with the LambdaGeo book Same Material theme (LambdaGeo CSS, light/dark toggle), MathJax and Mermaid setup, tabbed navigation (Home, Getting started, Guides, Architecture, Reference, Validation) and a common "DisSModel ecosystem" section on the home page. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01S4SjCckAQ8koVsqjYipUHr --- docs/index.md | 15 +- docs/javascripts/mathjax-config.js | 9 + docs/javascripts/mermaid-init.js | 3 + docs/stylesheets/lambdageo.css | 481 +++++++++++++++++++++++++++++ mkdocs.yml | 124 +++++--- 5 files changed, 592 insertions(+), 40 deletions(-) create mode 100644 docs/javascripts/mathjax-config.js create mode 100644 docs/javascripts/mermaid-init.js create mode 100644 docs/stylesheets/lambdageo.css diff --git a/docs/index.md b/docs/index.md index 87e3e77..2527570 100644 --- a/docs/index.md +++ b/docs/index.md @@ -61,7 +61,7 @@ env.run(30) --- -## 📦 Model Ecosystem +## Model libraries To keep the core framework lean, we maintain specialized libraries containing ready-to-use models. These are excellent starting points for your own research: @@ -71,6 +71,15 @@ To keep the core framework lean, we maintain specialized libraries containing re --- -## License +## The DisSModel ecosystem -MIT © 2026 Sérgio Costa & Nerval Santos Junior — [LambdaGeo/UFMA](https://github.com/DisSModel) \ No newline at end of file +| Package | Role | Documentation | +|:---|:---|:---| +| [**dissmodel**](https://github.com/DisSModel/dissmodel) | Core framework: clock, spatial substrates, executor, I/O, visualization | [dissmodel.github.io/dissmodel](https://dissmodel.github.io/dissmodel/) | +| [**disscube**](https://github.com/DisSModel/disscube) | Declarative pipelines that turn raster and vector sources into model-ready grids | [dissmodel.github.io/disscube](https://dissmodel.github.io/disscube/) | +| [**disslucc**](https://github.com/DisSModel/disslucc) | Land use and cover change: demand, potential and allocation | [dissmodel.github.io/disslucc](https://dissmodel.github.io/disslucc/) | +| [dissmodel-ca](https://github.com/DisSModel/dissmodel-ca), [dissmodel-sysdyn](https://github.com/DisSModel/dissmodel-sysdyn), [dissmodel-abm](https://github.com/DisSModel/dissmodel-abm) | Ready-to-use cellular automata, system dynamics and agent-based models | GitHub | + +Developed by the [LambdaGeo](https://github.com/LambdaGeo) group at the Federal University of Maranhão (UFMA). MIT licence. + +Copyright © 2026 Sérgio Costa & Nerval Santos Junior. diff --git a/docs/javascripts/mathjax-config.js b/docs/javascripts/mathjax-config.js new file mode 100644 index 0000000..1e76ce2 --- /dev/null +++ b/docs/javascripts/mathjax-config.js @@ -0,0 +1,9 @@ +// Accept $...$ for inline math (as well as \(...\)) in notebook markdown cells. +window.MathJax = { + tex: { + inlineMath: [["$", "$"], ["\\(", "\\)"]], + displayMath: [["$$", "$$"], ["\\[", "\\]"]], + processEscapes: true + }, + options: { skipHtmlTags: ["script", "noscript", "style", "textarea", "pre", "code"] } +}; diff --git a/docs/javascripts/mermaid-init.js b/docs/javascripts/mermaid-init.js new file mode 100644 index 0000000..33759a9 --- /dev/null +++ b/docs/javascripts/mermaid-init.js @@ -0,0 +1,3 @@ +document.addEventListener("DOMContentLoaded", function() { + mermaid.initialize({ startOnLoad: true }); +}); \ No newline at end of file diff --git a/docs/stylesheets/lambdageo.css b/docs/stylesheets/lambdageo.css new file mode 100644 index 0000000..952e52a --- /dev/null +++ b/docs/stylesheets/lambdageo.css @@ -0,0 +1,481 @@ +/* + * LambdaGeo — identidade visual para livros MkDocs Material + * Paleta oficial, tipografia Inter, componentes modernizados. + * Toda a personalização do tema vive neste arquivo; nenhum arquivo + * interno do tema é sobrescrito. + */ + +/* Fonte Inter — pesos 400/500/600/700 (regular + itálico no peso base) */ +@import url("https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap"); + +/* ---------------------------------------------------------------- * + * 1. Variáveis de marca + * ---------------------------------------------------------------- */ +:root { + --lg-primary: #1565c0; /* Azul */ + --lg-secondary: #2e7d32; /* Verde */ + --lg-accent: #00acc1; /* Ciano */ + --lg-dark: #263238; /* Grafite */ + --lg-light: #fafafa; /* Branco */ + + /* Tons derivados, usados em hover/estados e no modo escuro */ + --lg-primary-light: #5e92f3; + --lg-primary-dark: #003c8f; + --lg-secondary-light: #60ad5e; + --lg-secondary-dark: #005005; + --lg-accent-light: #5ddef4; + --lg-accent-dark: #007c91; + --lg-dark-light: #4f5b62; + --lg-dark-dark: #000a12; + + /* Escala tipográfica (pesos Inter: 400/500/600/700) */ + --lg-font-body: 400; + --lg-font-medium: 500; + --lg-font-semibold: 600; + --lg-font-bold: 700; + + /* Ritmo vertical / largura de leitura */ + --lg-reading-width: 46rem; + --lg-radius: 10px; + --lg-radius-sm: 6px; +} + +/* ---------------------------------------------------------------- * + * 2. Tipografia — Inter em toda a documentação + * ---------------------------------------------------------------- */ +:root, +[data-md-color-scheme] { + --md-text-font: "Inter", "-apple-system", "Helvetica Neue", Arial, sans-serif; + /* Fonte monoespaçada do sistema: evita uma segunda requisição de fonte externa */ + --md-code-font: ui-monospace, "SFMono-Regular", "Menlo", "Consolas", + "Liberation Mono", monospace; +} + +.md-typeset { + font-weight: var(--lg-font-body); + line-height: 1.7; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4, +.md-typeset h5, +.md-typeset h6 { + font-family: var(--md-text-font); + letter-spacing: -0.01em; + color: var(--lg-dark); +} + +[data-md-color-scheme="slate"] .md-typeset h1, +[data-md-color-scheme="slate"] .md-typeset h2, +[data-md-color-scheme="slate"] .md-typeset h3, +[data-md-color-scheme="slate"] .md-typeset h4, +[data-md-color-scheme="slate"] .md-typeset h5, +[data-md-color-scheme="slate"] .md-typeset h6 { + color: var(--lg-light); +} + +.md-typeset h1 { + font-weight: var(--lg-font-bold); + font-size: 2.1rem; + margin-bottom: 1.4rem; +} + +.md-typeset h2 { + font-weight: var(--lg-font-semibold); + font-size: 1.55rem; + margin-top: 2.4rem; + padding-bottom: 0.4rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset h3 { + font-weight: var(--lg-font-semibold); + font-size: 1.2rem; + margin-top: 1.9rem; +} + +.md-typeset h4 { + font-weight: var(--lg-font-medium); + font-size: 1.05rem; +} + +.md-typeset p, +.md-typeset ul, +.md-typeset ol { + margin-bottom: 1.1rem; +} + +/* Navegação lateral, breadcrumbs e TOC usam peso médio para hierarquia clara */ +.md-nav { + font-weight: var(--lg-font-medium); + font-size: 0.7rem; +} + +.md-nav__title { + font-weight: var(--lg-font-semibold); +} + +.md-nav__item .md-nav__link--active, +.md-nav__link:focus, +.md-nav__link:hover { + color: var(--lg-primary); +} + +[data-md-color-scheme="slate"] .md-nav__item .md-nav__link--active { + color: var(--lg-accent-light); +} + +/* ---------------------------------------------------------------- * + * 3. Paleta — modo claro + * ---------------------------------------------------------------- */ +[data-md-color-scheme="default"] { + --md-primary-fg-color: var(--lg-primary); + --md-primary-fg-color--light: var(--lg-primary-light); + --md-primary-fg-color--dark: var(--lg-primary-dark); + --md-primary-bg-color: var(--lg-light); + --md-primary-bg-color--light: var(--lg-light); + + --md-accent-fg-color: var(--lg-accent); + --md-accent-fg-color--transparent: rgba(0, 172, 193, 0.1); + --md-accent-bg-color: var(--lg-light); + + --md-default-bg-color: var(--lg-light); + --md-default-fg-color: var(--lg-dark); + --md-default-fg-color--light: #445056; + --md-default-fg-color--lighter: #78878e; + --md-default-fg-color--lightest: #e3e8ea; + + --md-typeset-color: var(--lg-dark); + --md-typeset-a-color: var(--lg-primary); + + --md-footer-bg-color: var(--lg-dark); + --md-footer-bg-color--dark: var(--lg-dark-dark); + --md-footer-fg-color: var(--lg-light); + --md-footer-fg-color--light: rgba(250, 250, 250, 0.7); +} + +/* ---------------------------------------------------------------- * + * 4. Paleta — modo escuro (alto contraste sobre grafite) + * ---------------------------------------------------------------- */ +[data-md-color-scheme="slate"] { + --md-primary-fg-color: var(--lg-dark); + --md-primary-fg-color--light: var(--lg-dark-light); + --md-primary-fg-color--dark: var(--lg-dark-dark); + --md-primary-bg-color: var(--lg-light); + + --md-accent-fg-color: var(--lg-accent-light); + --md-accent-fg-color--transparent: rgba(93, 222, 244, 0.15); + + --md-default-bg-color: #1b2529; + --md-default-fg-color: #eceff1; + --md-default-fg-color--light: #cfd8dc; + --md-default-fg-color--lighter: #90a4ae; + --md-default-fg-color--lightest: #37474f; + + --md-typeset-color: #eceff1; + --md-typeset-a-color: #7aa9ff; + + --md-code-bg-color: #0f1719; + --md-code-fg-color: #eceff1; + + --md-footer-bg-color: #14181a; + --md-footer-bg-color--dark: #0c0e0f; +} + +/* ---------------------------------------------------------------- * + * 5. Cabeçalho — sem logotipo, apenas título/subtítulo + * ---------------------------------------------------------------- */ +.md-header__title { + font-weight: var(--lg-font-semibold); +} + +.md-header__button.md-logo { + display: none; +} + +/* ---------------------------------------------------------------- * + * 6. Largura de leitura e espaçamento + * ---------------------------------------------------------------- */ +.md-grid { + max-width: 76rem; +} + +.md-typeset { + max-width: var(--lg-reading-width); + margin-left: auto; + margin-right: auto; +} + +/* Tabelas, blocos de código e admonitions podem usar a largura toda do artigo */ +.md-typeset table:not([class]), +.md-typeset pre, +.md-typeset .admonition, +.md-typeset .tabbed-set, +.md-typeset .grid { + max-width: 100%; +} + +@media screen and (max-width: 76.1875em) { + .md-typeset { + max-width: none; + } +} + +/* ---------------------------------------------------------------- * + * 7. Admonitions — cores consistentes com a marca + * ---------------------------------------------------------------- */ +.md-typeset .admonition, +.md-typeset details { + border-radius: var(--lg-radius-sm); + border-width: 1px; +} + +/* Note → azul da marca */ +.md-typeset .admonition.note, +.md-typeset details.note { + border-color: var(--lg-primary); +} +.md-typeset .note > .admonition-title, +.md-typeset .note > summary { + background-color: rgba(21, 101, 192, 0.08); +} +.md-typeset .note > .admonition-title::before, +.md-typeset .note > summary::before { + background-color: var(--lg-primary); +} + +/* Tip / Success → verde da marca */ +.md-typeset .admonition.tip, +.md-typeset details.tip, +.md-typeset .admonition.success, +.md-typeset details.success { + border-color: var(--lg-secondary); +} +.md-typeset .tip > .admonition-title, +.md-typeset .tip > summary, +.md-typeset .success > .admonition-title, +.md-typeset .success > summary { + background-color: rgba(46, 125, 50, 0.08); +} +.md-typeset .tip > .admonition-title::before, +.md-typeset .tip > summary::before, +.md-typeset .success > .admonition-title::before, +.md-typeset .success > summary::before { + background-color: var(--lg-secondary); +} + +/* Question / Info → ciano da marca (complementa nota/dica) */ +.md-typeset .admonition.question, +.md-typeset details.question, +.md-typeset .admonition.info, +.md-typeset details.info { + border-color: var(--lg-accent); +} +.md-typeset .question > .admonition-title, +.md-typeset .question > summary, +.md-typeset .info > .admonition-title, +.md-typeset .info > summary { + background-color: rgba(0, 172, 193, 0.08); +} +.md-typeset .question > .admonition-title::before, +.md-typeset .question > summary::before, +.md-typeset .info > .admonition-title::before, +.md-typeset .info > summary::before { + background-color: var(--lg-accent); +} + +/* Warning e Danger permanecem no padrão do Material (laranja / vermelho) */ + +/* ---------------------------------------------------------------- * + * 8. Blocos de código + * ---------------------------------------------------------------- */ +.md-typeset pre > code, +.md-typeset .highlight { + border-radius: var(--lg-radius); +} + +.md-typeset pre { + border-radius: var(--lg-radius); + padding: 0.2rem 0.2rem; +} + +.md-typeset code { + border-radius: 4px; + font-weight: var(--lg-font-medium); +} + +.md-typeset .highlighttable, +.md-typeset .highlight pre { + border-radius: var(--lg-radius); +} + +.md-clipboard { + border-radius: 4px; +} + +.md-clipboard:hover { + color: var(--lg-accent); +} + +/* ---------------------------------------------------------------- * + * 9. Tabelas + * ---------------------------------------------------------------- */ +.md-typeset table:not([class]) { + border-radius: var(--lg-radius-sm); + overflow: hidden; + border: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset table:not([class]) th { + background-color: var(--lg-primary); + color: var(--lg-light); + font-weight: var(--lg-font-semibold); +} + +.md-typeset table:not([class]) tr:nth-child(even) { + background-color: rgba(21, 101, 192, 0.035); +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) tr:nth-child(even) { + background-color: rgba(255, 255, 255, 0.03); +} + +/* ---------------------------------------------------------------- * + * 10. Links, botões, abas + * ---------------------------------------------------------------- */ +.md-typeset a { + font-weight: var(--lg-font-medium); + text-decoration-thickness: 1px; + text-underline-offset: 2px; +} + +.md-typeset a:hover { + color: var(--lg-accent); +} + +.md-typeset .md-button { + border-radius: var(--lg-radius-sm); + font-weight: var(--lg-font-semibold); + border-color: var(--lg-primary); + color: var(--lg-primary); +} + +.md-typeset .md-button:hover, +.md-typeset .md-button--primary:hover { + background-color: var(--lg-primary); + border-color: var(--lg-primary); + color: var(--lg-light); +} + +.md-typeset .md-button--primary { + background-color: var(--lg-primary); + border-color: var(--lg-primary); + color: var(--lg-light); +} + +.md-typeset .tabbed-set > .tabbed-labels > label { + font-weight: var(--lg-font-medium); + border-radius: var(--lg-radius-sm) var(--lg-radius-sm) 0 0; +} + +.md-typeset .tabbed-set > input:checked + label { + color: var(--lg-primary); + border-color: var(--lg-primary); +} + +/* ---------------------------------------------------------------- * + * 11. Cards e grids (pymdownx / Material "grid cards") + * ---------------------------------------------------------------- */ +.md-typeset .grid.cards > ul > li, +.md-typeset .grid > .card { + border-radius: var(--lg-radius); + border: 1px solid var(--md-default-fg-color--lightest); + transition: border-color 0.15s, transform 0.15s, box-shadow 0.15s; +} + +.md-typeset .grid.cards > ul > li:hover { + border-color: var(--lg-accent); + box-shadow: 0 6px 16px rgba(0, 0, 0, 0.08); + transform: translateY(-2px); +} + +/* ---------------------------------------------------------------- * + * 12. Badges (utilitário — para uso opcional em HTML embutido) * + * ---------------------------------------------------------------- */ +.lg-badge { + display: inline-block; + padding: 0.1rem 0.55rem; + border-radius: 999px; + font-size: 0.7rem; + font-weight: var(--lg-font-semibold); + line-height: 1.6; + color: var(--lg-light); + background-color: var(--lg-dark-light); +} + +.lg-badge--primary { background-color: var(--lg-primary); } +.lg-badge--secondary { background-color: var(--lg-secondary); } +.lg-badge--accent { background-color: var(--lg-accent); } + +/* ---------------------------------------------------------------- * + * 13. Rodapé + * ---------------------------------------------------------------- */ +.md-footer-meta { + background-color: var(--lg-dark-dark); +} + +.md-footer__link:hover .md-footer__title, +.md-footer__link:hover .md-footer__direction { + color: var(--lg-accent-light); +} + +/* ---------------------------------------------------------------- * + * 14. Busca + * ---------------------------------------------------------------- */ +.md-search-result__meta { + color: var(--md-default-fg-color--light); +} + +mark { + background-color: rgba(0, 172, 193, 0.35); + color: inherit; +} + +/* ---------------------------------------------------------------- * + * 15. Acessibilidade — foco visível + * ---------------------------------------------------------------- */ +a:focus-visible, +button:focus-visible, +.md-nav__link:focus-visible, +.md-tabs__link:focus-visible, +input:focus-visible { + outline: 2px solid var(--lg-accent); + outline-offset: 2px; + border-radius: 2px; +} + +/* ---------------------------------------------------------------- * + * 16. Responsividade fina + * ---------------------------------------------------------------- */ +@media screen and (max-width: 44.9375em) { + .md-typeset h1 { font-size: 1.7rem; } + .md-typeset h2 { font-size: 1.3rem; } + .md-typeset pre { padding: 0.1rem; } + + /* Material's default mobile gutter (0.8rem) is too tight for long-form + reading; give the text more breathing room on phone-sized screens. */ + .md-content__inner { + margin-left: 1.25rem; + margin-right: 1.25rem; + } +} + +/* Wide display equations scroll sideways instead of being clipped on phones. */ +.md-typeset mjx-container[display="true"], +.md-typeset .arithmatex { + overflow-x: auto; + overflow-y: hidden; + max-width: 100%; +} diff --git a/mkdocs.yml b/mkdocs.yml index 6421c36..c347f82 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,44 @@ site_name: DisSModel +site_description: "Discrete spatial modeling framework for Python: cellular automata and system dynamics on vector and raster substrates." +site_author: "LambdaGeo / UFMA" site_url: https://dissmodel.github.io/dissmodel/ repo_url: https://github.com/DisSModel/dissmodel -repo_name: dissmodel +repo_name: DisSModel/dissmodel +edit_uri: edit/main/docs/ + +theme: + name: material + language: en + font: false + features: + - navigation.tabs + - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.top + - search.highlight + - search.share + - content.code.annotate + - content.code.copy + - content.tabs.link + - content.tooltips + - content.action.edit + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: custom + accent: custom + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: custom + accent: custom + toggle: + icon: material/weather-night + name: Switch to light mode plugins: - search @@ -15,48 +52,61 @@ plugins: show_root_heading: true - mkdocs-jupyter: include: ["*.ipynb"] - -theme: - name: material - language: en - palette: - - scheme: default - primary: teal - accent: green - - + execute: false markdown_extensions: - - codehilite - - pymdownx.highlight - - pymdownx.superfences + - attr_list + - admonition + - pymdownx.details - pymdownx.arithmatex: generic: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - tables + - toc: + permalink: true + +extra_css: + - stylesheets/lambdageo.css extra_javascript: + - javascripts/mathjax-config.js - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + - https://unpkg.com/mermaid@10/dist/mermaid.min.js + - javascripts/mermaid-init.js nav: - Home: index.md - - Getting Started: getting_started.md - - Why DisSModel?: why_dissmodel.md - - Examples: - - Overview: examples.md - - CLI Examples: examples/cli.md - - Streamlit Examples: examples/streamlit.md - - Vector to Raster: examples/vector_to_raster.md - - Notebooks: - - Game of Life: examples/notebooks/ca_game_of_life.ipynb - - SIR Model: examples/notebooks/sysdyn_sir.ipynb - - API Reference: - - Core: api/core.md - - Geo: - - Overview: api/geo/index.md - - Vector: api/geo/vector.md - - Raster: api/geo/raster.md - - Executor: - - Overview: api/executor/index.md - - Schemas: api/executor/schemas.md - - CLI: api/executor/cli.md - - Testing: api/executor/testing.md - - IO: api/io/index.md - - Visualization: api/visualization.md + - Getting started: + - Installation and first model: getting_started.md + - Guides: + - Why DisSModel?: why_dissmodel.md + - Examples: + - Overview: examples.md + - CLI Examples: examples/cli.md + - Streamlit Examples: examples/streamlit.md + - Vector to Raster: examples/vector_to_raster.md + - Notebooks: + - Game of Life: examples/notebooks/ca_game_of_life.ipynb + - SIR Model: examples/notebooks/sysdyn_sir.ipynb + - Reference: + - Core: api/core.md + - Geo: + - Overview: api/geo/index.md + - Vector: api/geo/vector.md + - Raster: api/geo/raster.md + - Executor: + - Overview: api/executor/index.md + - Schemas: api/executor/schemas.md + - CLI: api/executor/cli.md + - Testing: api/executor/testing.md + - IO: api/io/index.md + - Visualization: api/visualization.md