diff --git a/CHANGELOG.md b/CHANGELOG.md index 7cc3be435..41dae8ad4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,6 +70,7 @@ If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flix ### 📦 Dependencies ### 📝 Docs +- Improve docs visually ### 👷 Development diff --git a/docs/index.md b/docs/index.md index 6723c4d5e..a7cd67f8c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,144 @@ -{% - include-markdown "../README.md" -%} - --- +title: Home +hide: + - navigation + - toc +--- + +
+ +

flixOpt

+ +

Energy and Material Flow Optimization Framework

+ +

Model, optimize, and analyze complex energy systems with a powerful Python framework designed for flexibility and performance.

+ +

+ 🚀 Get Started + 💡 View Examples + ⭐ GitHub +

+ +
+ +## :material-map-marker-path: Quick Navigation + +
+ +

🚀 Getting Started

+

New to FlixOpt? Start here with installation and your first model

+ + + +

💡 Examples Gallery

+

Explore real-world examples from simple to complex systems

+ -## Documentation Architecture + +

📚 API Reference

+

Detailed documentation of all classes, methods, and parameters

+ + + +

📖 Recipes

+

Common patterns and best practices for modeling energy systems

+ + + +

∫ Mathematical Notation

+

Understand the mathematical formulations behind the framework

+ + + +

🛣️ Roadmap

+

See what's coming next and contribute to the future of FlixOpt

+ +
+ +## 🏗️ Framework Architecture + +
![FlixOpt Conceptual Usage](./images/architecture_flixOpt.png)
Conceptual Usage and IO operations of FlixOpt
+**FlixOpt** provides a complete workflow for energy system optimization: + +- **:material-file-code: Define** your system using Python components +- **:material-cog: Optimize** with powerful solvers (HiGHS, Gurobi, CPLEX) +- **:material-chart-box: Analyze** results with built-in visualization tools +- **:material-export: Export** to various formats for further analysis + +
+ +## :material-account-group: Community & Support + +
+ +
+ +:fontawesome-brands-github:{ .feature-icon } + +### GitHub + +Report issues, request features, and contribute to the codebase + +[Visit Repository →](https://github.com/flixOpt/flixopt){target="_blank" rel="noopener noreferrer"} + +
+ +
+ +:material-forum:{ .feature-icon } + +### Discussions + +Ask questions and share your projects with the community + +[Join Discussion →](https://github.com/flixOpt/flixopt/discussions){target="_blank" rel="noopener noreferrer"} + +
+ +
+ +:material-book-open-page-variant:{ .feature-icon } + +### Contributing + +Help improve FlixOpt by contributing code, docs, or examples + +[Learn How →](contribute/){target="_blank" rel="noopener noreferrer"} + +
+ +
+ + +## :material-file-document-edit: Recent Updates + +!!! tip "What's New in v3.0.0" + Major improvements and breaking changes. Check the [Migration Guide](user-guide/migration-guide-v3.md) for upgrading from v2.x. + +📋 See the full [Release Notes](changelog/) for detailed version history. + --- -## Next Steps +
+ +

Ready to optimize your energy system?

+ +

+ ▶️ Start Building +

-- **New to FlixOpt?** Start with the [Getting Started Guide](getting-started.md) -- **Want to see examples?** Check out the [Examples Gallery](examples/index.md) -- **Need API details?** Browse the [API Reference](api-reference/index.md) -- **Looking for advanced patterns?** See [Recipes](user-guide/recipes/index.md) -- **Curious about the future?** Read our [Roadmap](roadmap.md) +
+ +--- + +{% + include-markdown "../README.md" + start="## Installation" + end="## License" +%} diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 000000000..79dfc9a15 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,396 @@ +/* ============================================================================ + flixOpt Custom Styling + ========================================================================= */ + +/* Root variables for easy customization */ +:root { + /* Spacing */ + --content-padding: 2rem; + + /* Typography */ + --heading-font-weight: 600; + + /* Colors - enhance teal theme */ + --flixopt-teal: #009688; + --flixopt-teal-light: #4DB6AC; + --flixopt-teal-dark: #00796B; +} + +/* Dark mode adjustments */ +[data-md-color-scheme="slate"] { + --md-code-bg-color: #1e1e1e; +} + +/* ============================================================================ + Typography Improvements + ========================================================================= */ + +/* Better line height for readability */ +.md-typeset { + line-height: 1.7; +} + +/* Enhanced headings */ +.md-typeset h1 { + font-weight: var(--heading-font-weight); + letter-spacing: -0.02em; + margin-top: 0; +} + +.md-typeset h2 { + font-weight: var(--heading-font-weight); + border-bottom: 1px solid var(--md-default-fg-color--lightest); + padding-bottom: 0.3em; + margin-top: 2em; +} + +/* Better code inline */ +.md-typeset code { + padding: 0.15em 0.4em; + border-radius: 0.25em; + font-size: 0.875em; +} + +/* ============================================================================ + Navigation Enhancements + ========================================================================= */ + +/* Smooth hover effects on navigation */ +.md-nav__link:hover { + opacity: 0.7; + transition: opacity 0.2s ease; +} + +/* Active navigation item enhancement */ +.md-nav__link--active { + font-weight: 600; + border-left: 3px solid var(--md-primary-fg-color); + padding-left: calc(1.2rem - 3px) !important; +} + +/* ============================================================================ + Code Block Improvements + ========================================================================= */ + +/* Better code block styling */ +.md-typeset .highlight { + border-radius: 0.5rem; + margin: 1.5em 0; + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); +} + +[data-md-color-scheme="slate"] .md-typeset .highlight { + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); +} + +/* Line numbers styling */ +.md-typeset .highlight .linenos { + user-select: none; + opacity: 0.5; +} + +/* Copy button enhancement */ +.md-clipboard { + opacity: 0; + transition: opacity 0.2s ease; +} + +.highlight:hover .md-clipboard { + opacity: 1; +} + +/* ============================================================================ + Admonitions & Callouts + ========================================================================= */ + +/* Enhanced admonitions */ +.md-typeset .admonition { + border-radius: 0.5rem; + border-left-width: 0.25rem; + box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05); +} + +/* ============================================================================ + Tables + ========================================================================= */ + +/* Better table styling */ +.md-typeset table:not([class]) { + border-radius: 0.5rem; + overflow: hidden; + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05); +} + +.md-typeset table:not([class]) th { + background-color: var(--md-primary-fg-color); + color: white; + font-weight: 600; + text-align: left; +} + +.md-typeset table:not([class]) tr:hover { + background-color: var(--md-default-fg-color--lightest); + transition: background-color 0.2s ease; +} + +/* ============================================================================ + API Documentation Styling + ========================================================================= */ + +/* Better spacing for API docs */ +.doc-heading { + margin-top: 2rem !important; +} + +/* Parameter tables */ +.doc-md-description table { + width: 100%; + font-size: 0.9em; +} + +/* Signature styling */ +.doc-signature { + font-family: var(--md-code-font); + background-color: var(--md-code-bg-color); + border-radius: 0.5rem; + padding: 1rem; + overflow-x: auto; +} + +/* ============================================================================ + Home Page Hero (optional enhancement) + ========================================================================= */ + +.hero { + text-align: center; + padding: 4rem 2rem; + background: linear-gradient(135deg, var(--flixopt-teal-light) 0%, var(--flixopt-teal-dark) 100%); + color: white; + border-radius: 1rem; + margin-bottom: 2rem; +} + +.hero h1 { + font-size: 3rem; + margin-bottom: 1rem; + color: white; + border: none; +} + +.hero p { + font-size: 1.25rem; + opacity: 0.9; +} + +/* ============================================================================ + Responsive Design + ========================================================================= */ + +@media screen and (max-width: 76.1875em) { + .md-typeset h1 { + font-size: 2rem; + } +} + +@media screen and (max-width: 44.9375em) { + :root { + --content-padding: 1rem; + } + + .hero h1 { + font-size: 2rem; + } + + .hero p { + font-size: 1rem; + } +} + +/* ============================================================================ + Print Styles + ========================================================================= */ + +@media print { + .md-typeset { + font-size: 0.9rem; + } + + .md-header, + .md-sidebar, + .md-footer { + display: none; + } +} + +/* ============================================================================ + Home Page Inline Styles (moved from docs/index.md) + ========================================================================= */ + +.hero-section { + text-align: center; + padding: 4rem 2rem 3rem 2rem; + background: linear-gradient(135deg, rgba(0, 150, 136, 0.1) 0%, rgba(0, 121, 107, 0.1) 100%); + border-radius: 1rem; + margin-bottom: 3rem; +} + +.hero-section h1 { + font-size: 3.5rem; + font-weight: 700; + margin-bottom: 1rem; + background: linear-gradient(135deg, #009688 0%, #00796B 100%); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +.hero-section .tagline { + font-size: 1.5rem; + color: var(--md-default-fg-color--light); + margin-bottom: 2rem; + font-weight: 300; +} + +.hero-buttons { + display: flex; + gap: 1rem; + justify-content: center; + flex-wrap: wrap; + margin-top: 2rem; +} + +.feature-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 2rem; + margin: 3rem 0; +} + +.feature-card { + padding: 2rem; + border-radius: 0.75rem; + background: var(--md-code-bg-color); + border: 1px solid var(--md-default-fg-color--lightest); + transition: all 0.3s ease; + text-align: center; +} + +.feature-card:hover { + transform: translateY(-4px); + box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1); + border-color: var(--md-primary-fg-color); +} + +.feature-icon { + font-size: 3rem; + margin-bottom: 1rem; + display: block; +} + +.feature-card h3 { + margin-top: 0; + margin-bottom: 0.5rem; + font-size: 1.25rem; +} + +.feature-card p { + color: var(--md-default-fg-color--light); + margin: 0; + font-size: 0.95rem; + line-height: 1.6; +} + +.stats-banner { + display: flex; + justify-content: space-around; + padding: 2rem; + background: var(--md-code-bg-color); + border-radius: 0.75rem; + margin: 3rem 0; + text-align: center; + flex-wrap: wrap; + gap: 2rem; +} + +.stat-item { + flex: 1; + min-width: 150px; +} + +.stat-number { + font-size: 2.5rem; + font-weight: 700; + color: var(--md-primary-fg-color); + display: block; +} + +.stat-label { + color: var(--md-default-fg-color--light); + font-size: 0.9rem; + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.architecture-section { + margin: 4rem 0; + padding: 2rem; + background: var(--md-code-bg-color); + border-radius: 0.75rem; +} + +.quick-links { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 1.5rem; + margin: 3rem 0; +} + +.quick-link-card { + padding: 1.5rem; + border-left: 4px solid var(--md-primary-fg-color); + background: var(--md-code-bg-color); + border-radius: 0.5rem; + transition: all 0.2s ease; + text-decoration: none; + display: block; +} + +.quick-link-card:hover { + background: var(--md-default-fg-color--lightest); + transform: translateX(4px); +} + +.quick-link-card h3 { + margin: 0 0 0.5rem 0; + font-size: 1.1rem; + color: var(--md-primary-fg-color); +} + +.quick-link-card p { + margin: 0; + color: var(--md-default-fg-color--light); + font-size: 0.9rem; +} + +@media screen and (max-width: 768px) { + .hero-section h1 { + font-size: 2.5rem; + } + + .hero-section .tagline { + font-size: 1.2rem; + } + + .hero-buttons { + flex-direction: column; + align-items: stretch; + } + + .feature-grid { + grid-template-columns: 1fr; + } + + .stats-banner { + flex-direction: column; + } +} diff --git a/mkdocs.yml b/mkdocs.yml index 8ed2c4b2c..cc108e237 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -# Options: +# flixOpt Documentation Configuration # https://mkdocstrings.github.io/python/usage/configuration/docstrings/ # https://squidfunk.github.io/mkdocs-material/setup/ @@ -39,126 +39,281 @@ nav: - API Reference: api-reference/ - Release Notes: changelog/ - theme: name: material + language: en + palette: - # Light mode + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode - media: "(prefers-color-scheme: light)" scheme: default primary: teal - accent: blue + accent: cyan toggle: icon: material/brightness-7 name: Switch to dark mode - # Dark mode + + # Palette toggle for dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: teal # Can be different from light mode - accent: blue + primary: teal + accent: cyan toggle: icon: material/brightness-4 - name: Switch to light mode + name: Switch to system preference + + font: + text: Inter # Modern, readable font + code: Fira Code # Beautiful code font with ligatures + logo: images/flixopt-icon.svg favicon: images/flixopt-icon.svg + icon: repo: fontawesome/brands/github + edit: material/pencil + view: material/eye + annotation: material/plus-circle + features: + # Navigation - navigation.instant - navigation.instant.progress + - navigation.instant.prefetch - navigation.tracking - navigation.tabs + - navigation.tabs.sticky - navigation.sections + - navigation.expand # Expand navigation by default + - navigation.path # Show breadcrumb path + - navigation.prune # Only render visible navigation + - navigation.indexes - navigation.top - navigation.footer + + # Table of contents - toc.follow - - navigation.indexes + - toc.integrate # Integrate TOC into navigation (optional) + + # Search - search.suggest - search.highlight + - search.share + + # Content - content.action.edit - content.action.view - content.code.copy + - content.code.select - content.code.annotate - content.tooltips - - navigation.footer.version + - content.tabs.link # Link content tabs across pages + + # Header + - announce.dismiss # Allow dismissing announcements markdown_extensions: + # Content formatting + - abbr - admonition - - markdown_include.include: - base_path: docs + - attr_list + - def_list + - footnotes + - md_in_html + - tables + - toc: + permalink: true + permalink_title: Anchor link to this section + toc_depth: 3 + + # Code blocks - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true + auto_title: true - pymdownx.inlinehilite + - pymdownx.snippets: + base_path: .. + check_paths: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + + # Enhanced content - pymdownx.details - - pymdownx.superfences - - attr_list - - abbr - - md_in_html - - footnotes - - tables - pymdownx.tabbed: alternate_style: true + combine_header_slug: true + - pymdownx.tasklist: + custom_checkbox: true + + # Typography + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.smartsymbols + - pymdownx.keys + + # Math - pymdownx.arithmatex: generic: true + + # Icons & emojis - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - - pymdownx.snippets: - base_path: .. + options: + custom_icons: + - overrides/.icons + + # Legacy support + - markdown_include.include: + base_path: docs plugins: - - search # Enables the search functionality in the documentation - - table-reader # Allows including tables from external files + - search: + separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' + + - table-reader + - include-markdown + - mike: + alias_type: symlink + redirect_template: null + deploy_prefix: '' + canonical_version: null version_selector: true + css_dir: css + javascript_dir: js + - literate-nav: nav_file: SUMMARY.md + implicit_index: true + - gen-files: scripts: - - scripts/gen_ref_pages.py - - mkdocstrings: # Handles automatic API documentation generation - default_handler: python # Sets Python as the default language - handlers: - python: # Configuration for Python code documentation - options: - docstring_style: google # Sets google as the docstring style - modernize_annotations: true # Improves type annotations - merge_init_into_class: true # Promotes constructor parameters to class-level documentation - docstring_section_style: table # Renders parameter sections as a table (also: list, spacy) - - members_order: source # Orders members as they appear in the source code - inherited_members: false # Include members inherited from parent classes - show_if_no_docstring: false # Documents objects even if they don't have docstrings - - group_by_category: true - heading_level: 1 # Sets the base heading level for documented objects - line_length: 80 - filters: ["!^_", "^__init__$"] - show_root_heading: true # whether the documented object's name should be displayed as a heading at the beginning of its documentation - show_source: false # Shows the source code implementation from documentation - show_object_full_path: false # Displays simple class names instead of full import paths - show_docstring_attributes: true # Shows class attributes in the documentation - show_category_heading: true # Displays category headings (Methods, Attributes, etc.) for organization - show_signature: true # Shows method signatures with parameters - show_signature_annotations: true # Includes type annotations in the signatures when available - show_root_toc_entry: false # Whether to show a link to the root of the documentation in the sidebar - separate_signature: true # Displays signatures separate from descriptions for cleaner layout - - extra: - infer_type_annotations: true # Uses Python type hints to supplement docstring information + - scripts/gen_ref_pages.py + + - mkdocstrings: + enabled: !ENV [ENABLE_MKDOCSTRINGS, true] + default_handler: python + handlers: + python: + paths: [.] + import: + - https://docs.python.org/3/objects.inv + - https://numpy.org/doc/stable/objects.inv + - https://pandas.pydata.org/docs/objects.inv + options: + # Docstring parsing + docstring_style: google + docstring_section_style: table + + # Member ordering and filtering + members_order: source + inherited_members: false + show_if_no_docstring: false + filters: ["!^_", "^__init__$"] + group_by_category: true + + # Headings and structure + heading_level: 1 + show_root_heading: true + show_root_toc_entry: false + show_category_heading: true + + # Signatures + show_signature: true + show_signature_annotations: true + separate_signature: true + line_length: 80 + + # Source and paths + show_source: false + show_object_full_path: false + + # Attributes and annotations + show_docstring_attributes: true + modernize_annotations: true + merge_init_into_class: true + + # Improved type hints + annotations_path: brief + + # Optional: Add git info + - git-revision-date-localized: + enable_creation_date: true + type: timeago + fallback_to_build_date: true + + # Optional: Add better navigation + - tags: + tags_file: tags.md + + # Optional: Minify HTML in production + - minify: + minify_html: true + minify_js: true + minify_css: true + htmlmin_opts: + remove_comments: true extra: version: provider: mike default: latest + alias: true + + social: + - icon: fontawesome/brands/github + link: https://github.com/flixOpt/flixopt + name: flixOpt on GitHub + - icon: fontawesome/brands/python + link: https://pypi.org/project/flixopt/ + name: flixOpt on PyPI + + analytics: + provider: google + property: !ENV GOOGLE_ANALYTICS_KEY + feedback: + title: Was this page helpful? + ratings: + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: >- + Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: >- + Thanks for your feedback! Help us improve by + opening an issue. + + status: + new: Recently added + deprecated: Deprecated + +extra_css: + - stylesheets/extra.css extra_javascript: - - javascripts/mathjax.js # Custom MathJax 3 CDN Configuration - - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js #MathJax 3 CDN - - https://polyfill.io/v3/polyfill.min.js?features=es6 #Support for older browsers + - javascripts/mathjax.js + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 watch: - flixopt + - docs diff --git a/pyproject.toml b/pyproject.toml index 9e1821a4b..227eca49e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,9 +34,9 @@ dependencies = [ # Core scientific computing "numpy >= 1.21.5, < 3", "pandas >= 2.0.0, < 3", - "xarray >= 2024.2.0, < 2026.0", # CalVer: allow through next calendar year + "xarray >= 2024.2.0, < 2026.0", # CalVer: allow through next calendar year # Optimization and data handling - "linopy >= 0.5.1, < 0.6", # Widened from patch pin to minor range + "linopy >= 0.5.1, < 0.6", # Widened from patch pin to minor range "h5netcdf>=1.0.0, < 2", # Utilities "pyyaml >= 6.0.0, < 7", @@ -44,13 +44,11 @@ dependencies = [ "tomli >= 2.0.1, < 3; python_version < '3.11'", # Only needed with python 3.10 or earlier # Default solver "highspy >= 1.5.3, < 2", - # Visualization "matplotlib >= 3.5.2, < 4", "plotly >= 5.15.0, < 7", - # Fix for numexpr compatibility issue with numpy 1.26.4 on Python 3.10 - "numexpr >= 2.8.4, < 2.14; python_version < '3.11'", # Avoid 2.14.0 on older Python + "numexpr >= 2.8.4, < 2.14; python_version < '3.11'", # Avoid 2.14.0 on older Python ] [project.optional-dependencies] @@ -98,6 +96,7 @@ dev = [ # Documentation building docs = [ + "mkdocs==1.6.1", "mkdocs-material==9.6.21", "mkdocstrings-python==1.18.2", "mkdocs-table-reader-plugin==3.1.0", @@ -108,6 +107,8 @@ docs = [ "pymdown-extensions==10.16.1", "pygments==2.19.2", "mike==2.1.3", + "mkdocs-git-revision-date-localized-plugin==1.4.7", + "mkdocs-minify-plugin==0.8.0", ] [project.urls]