Feature/docs improvement (#481)

* Flow.md - Fully restructured with:
    - Tab-based organization (Core / Advanced / Patterns / Examples)
    - Collapsible definition blocks
    - Links to both Flow and FlowModel classes
    - Updated docstrings with absolute URLs
  2. Bus.md - Restructured with tab organization and dual class linking
  3. Storage.md - Restructured with comprehensive examples and dual class linking
  4. LinearConverter.md - Restructured with detailed examples including specialized converters
  5. InvestParameters.md - Restructured with clear separation of core vs. advanced features

* Improve organization

* Improve organization

* Improve organization by using tables

* Improve organization by using tables and use eqref

* Add symbol to parameter mapping

* Changed to inline math

* Use propre constraints with numbering

* Move parameters into separate tab

* Reorder parameters

* : Use the columns "symbol" and "python name" in the variables tab

* Update Bus, Storage, and LinearConverter.md

* Update InvestParameters and OnOffParameters.md

* Update Piecewise.md

* Compact effects-penalty-objective.md

* Allow toc level 3

* Add toc to homepage

* Replace ustom css with mkdocs material stuff

* Revert some

* Revert some

* Remove layout css rule

* Show toc on homepage

* FIx broken link

* Add edit uri

* Hide bottom part

* Hide bottom part

* Restructure docs

* Show navigation in home

* Add Changelog fromating

* THighten CHANGELOG.md

* Simplify users.md

* Simplify models.md

* Shorten citing.md

* Shorten support.md

* Update CHANGELOG.md

* Simplify installation.md

* Simplify quick-start.md

* Updated FullCalculation → Optimization in documentation
 Fixed mkdocs.yml navigation
Fixed broken link in support.md

* Fixed solver calls in docs

* Move files and restructure

* Delete old docs script

* Improve docs structure

* Imrpove Optimization Modes

* Imrpove Optimization Modes

* Rewrite the core concepts to be user facing

* Reorganize Mathematical Notation

* 1. Minimal variable names — Changed from words to symbols:
    - penalty_rate → $c_\phi$
    - relative_min → $p_{rel}^{min}$
    - flow_hours → $h_f$
    - loss → $\dot{c}_{loss}$
    - etc.
  2. Tabs for conditional constraints — Used === "Tab Name" syntax for:
    - Bus.md: "Without Excess (Strict)" vs "With Excess (Soft)"
    - Flow.md: "Standard (No On/Off)" vs "With On/Off" vs "Fixed Profile"
    - Storage.md: "Fixed Initial" vs "Cyclic" vs "Final Bounds"
    - LinearConverter.md: "Single Input/Output" vs "Multiple Outputs" vs "COP > 1" vs "Time-Varying"
    - Effects.md: "Temporal (Operational)" vs "Periodic (Investment)" vs "Total"
  3. Corrected Flow constraints — Clarified that:
    - Without on/off parameters: flow cannot be zero if relative_minimum > 0
    - With on/off parameters: flow can be zero (when off) OR within bounds (when on)
  4. Cleaner structure — Removed redundant content, focused on essential formulas and examples

* The Flow.md now has four tabs for capacity bounds:

  1. Fixed Size — Standard bounds without on/off
  2. Fixed Size + On/Off — Can be zero when off
  3. Variable Size — Investment decision on capacity
  4. Variable Size + On/Off — Both investment and on/off, with big-M linearization for the bilinear term $s(t) \cdot P$

* InvestParameters.md:
  - Story-driven intro with real-world examples
  - Core concept: "Size as a Variable"
  - Tabs for: Binary (Fixed Size) | Continuous (Size Range) | Mandatory
  - Tabs for effects: Fixed | Specific | Retirement | Piecewise
  - Minimal variable names: $P$, $s_{inv}$, $c_{fix}$, $c_{spec}$, etc.
  - Cost annualization formula

  OnOffParameters.md:
  - Story-driven intro with real-world examples
  - Core concept: "Binary State" with flow bound modification
  - Tabs for state transitions: Switch Detection | Startup Costs | Running Costs
  - Tabs for duration constraints: Min Run Time | Min Off Time | Max Run Time | Total Hours | Max Startups
  - Minimal variable names: $s(t)$, $s^{on}(t)$, $s^{off}(t)$, $T_{on}^{min}$, etc.

  Piecewise.md:
  - Story-driven intro with ASCII diagram
  - Core concept: Linear segments with weighted combinations
  - Tabs for constraints: Single Piece Active | With Zero Point
  - Tabs for piece patterns: Continuous (Touching) | Gap (Forbidden Region) | Zero Point
  - Minimal variable names: $\beta_k$, $\lambda_0$, $\lambda_1$, etc.
  - Practical examples for heat pumps, boilers, and investment

* Make OnOffParameters better

* Piecewise.md:
  - Replaced the useless ASCII diagram with a more informative one showing:
    - Actual axis labels (input/output)
    - Numeric values on axes
    - Two pieces with their connection point labeled
    - Clear visual of how pieces connect at (50, 45)
    - Shows the start/end points notation

* Add plotly chart

* Add custom javascript

* Remove charts plugin

* Add missing docs file

* Fix quick start

* Delete model.md

* Update citation

* Update license.md

* Simplify faq, support and troubleshooting.md

* Remove old workflow

* 1. Renamed OnOffParameters.md → StatusParameters.md
  2. Updated all terminology:
    - on_off_parameters → status_parameters
    - OnOffParameters → StatusParameters
    - effects_per_switch_on → effects_per_startup
    - effects_per_running_hour → effects_per_active_hour
    - consecutive_on_hours_min → min_uptime
    - consecutive_on_hours_max → max_uptime
    - consecutive_off_hours_min → min_downtime
    - on_hours_min/max → active_hours_min/max
    - switch_on_max → startup_limit
    - switch_on/switch_off → startup/shutdown
    - "on/off" language → "active/inactive" language
  3. Updated references in Flow.md, LinearConverter.md, and effects-penalty-objective.md

* Remove Modeling patterns from docs

* Simplify docs

* Improve LinearConverter.md

* Improve Flow.md

* Improve effects-penalty-objective.md

* Improve InvestParameters.md

* Add durtaion constraints

* Update Piecewise stuff

* Update Piecewise stuff

* Update Piecewise stuff

* Combine effects and dimensions into one tab

* The dimension examples now correctly show how to assign them to FlowSystem using pd.Index:

* Update effects-and-dimensions.md

* Update effects-and-dimensions.md

* updated all reference tables across all Mathematical Notation pages to be consistent

* updated all reference tables across all Mathematical Notation pages to be consistent

* updated all reference tables across all Mathematical Notation pages to be consistent

Author: FBumann

.gitignore

@@ -8,3 +8,7 @@ venv/
 .DS_Store
 lib/
 temp-plot.html
+.cache
+site/
+*.egg-info
+uv.lock

CHANGELOG.md

@@ -16,7 +16,7 @@ This contains all commits, PRs, and contributors.
 Therefore, the Changelog should focus on the user-facing changes.
 
 Please remove all irrelevant sections before releasing.
-Please keep the format of the changelog consistent with the other releases, so the extraction for mkdocs works.
+Please keep the format of the changelog consistent: ## [VERSION] - YYYY-MM-DD
 ---
 
 ## [Template] - ????-??-??
@@ -49,11 +49,11 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 
 ---
 
-## [Unreleased] - ????-??-??
+Until here -->
 
-**Summary**: Renamed OnOff terminology to Status terminology for better alignment with PyPSA and unit commitment standards. **All deprecated items from v4.x have been removed.**
+## [Upcoming]
 
-### ✨ Added
+**Summary**: Renamed OnOff terminology to Status terminology for better alignment with PyPSA and unit commitment standards. **All deprecated items from v4.x have been removed.**
 
 ### 💥 Breaking Changes
 
@@ -212,22 +212,14 @@ A partial backwards compatibility wrapper would be misleading, so we opted for a
 - Flow parameters: `Q_fu` → use `fuel_flow`, `P_el` → use `electrical_flow`, `Q_th` → use `thermal_flow`, `Q_ab` → use `heat_source_flow`
 - Efficiency parameters: `eta` → use `thermal_efficiency`, `eta_th` → use `thermal_efficiency`, `eta_el` → use `electrical_efficiency`, `COP` → use `cop`
 
-### 🐛 Fixed
-
-### 🔒 Security
-
-### 📦 Dependencies
 
 ### 📝 Docs
+- Improve documentation from the ground up
 
-### 👷 Development
-
-### 🚧 Known Issues
+This is not yet publicly released!
 
 ---
 
-Until here -->
-
 ## [4.3.5] - 2025-11-29
 
 **Summary**: Fix zenodo again

README.md

@@ -96,7 +96,7 @@ boiler = fx.Boiler("Boiler", eta=0.9, ...)
 ### Key Features
 
 **Multi-criteria optimization:** Model costs, emissions, resource use - any custom metric. Optimize single objectives or use weighted combinations and ε-constraints.
-→ [Effects documentation](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/effects-penalty-objective/)
+→ [Effects documentation](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/effects-and-dimensions/)
 
 **Performance at any scale:** Choose optimization modes without changing your model - Optimization, SegmentedOptimization, or ClusteredOptimization (using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam)).
 → [Optimization modes](https://flixopt.github.io/flixopt/latest/api-reference/optimization/)

docs/getting-started.md

@@ -0,0 +1,29 @@
+# Citing flixOpt
+
+If you use flixOpt in your research, please cite it.
+
+## Citation
+
+When referencing flixOpt in academic publications, please use look here: [flixopt citation](https://zenodo.org/records/17756895)
+
+## Publications
+
+If you've published research using flixOpt, please let us know! We'd love to feature it here.
+
+### List of Publications
+
+*Coming soon: A list of academic publications that have used flixOpt*
+
+## Contributing Back
+
+If flixOpt helped your research:
+
+- Share your model as an example
+- Report issues or contribute code
+- Improve documentation
+
+See the [Contributing Guide](../contribute.md).
+
+## License
+
+flixOpt is released under the MIT License. See [License](license.md) for details.

docs/home/citing.md

@@ -0,0 +1,91 @@
+# Installation
+
+This guide covers installing flixOpt and its dependencies.
+
+
+## Basic Installation
+
+Install flixOpt directly into your environment using pip:
+
+```bash
+pip install flixopt
+```
+
+This provides the core functionality with the HiGHS solver included.
+
+## Full Installation
+
+For all features including interactive network visualizations and time series aggregation:
+
+```bash
+pip install "flixopt[full]"
+```
+
+## Development Installation
+
+If you want to contribute to flixOpt or work with the latest development version:
+
+```bash
+git clone https://github.com/flixOpt/flixopt.git
+cd flixopt
+pip install -e ".[full,dev,docs]"
+```
+
+## Solver Installation
+
+### HiGHS (Included)
+
+The HiGHS solver is included with flixOpt and works out of the box. No additional installation is required.
+
+### Gurobi (Optional)
+
+For academic use, Gurobi offers free licenses:
+
+1. Register for an academic license at [gurobi.com](https://www.gurobi.com/academia/)
+2. Install Gurobi:
+   ```bash
+   pip install gurobipy
+   ```
+3. Activate your license following Gurobi's instructions
+
+## Verification
+
+Verify your installation by running:
+
+```python
+import flixopt
+print(flixopt.__version__)
+```
+
+## Logging Configuration
+
+flixOpt uses Python's standard logging module with optional colored output via [colorlog](https://github.com/borntyping/python-colorlog). Logging is silent by default but can be easily configured:
+
+```python
+from flixopt import CONFIG
+
+# Enable colored console logging
+CONFIG.Logging.enable_console('INFO')
+
+# Or use a preset configuration for exploring
+CONFIG.exploring()
+```
+
+Since flixOpt uses Python's standard logging, you can also configure it directly:
+
+```python
+import logging
+
+# Get the flixopt logger and configure it
+logger = logging.getLogger('flixopt')
+logger.setLevel(logging.DEBUG)
+logger.addHandler(logging.StreamHandler())
+```
+
+For more details on logging configuration, see the [`CONFIG.Logging`][flixopt.config.CONFIG.Logging] documentation.
+
+## Next Steps
+
+- Follow the [Quick Start](quick-start.md) guide
+- Explore the [Minimal Example](../examples/00-Minimal Example.md)
+- Read about [Core Concepts](../user-guide/core-concepts.md)

docs/home/installation.md

@@ -0,0 +1,43 @@
+# License
+
+flixOpt is released under the MIT License.
+
+## MIT License
+
+```
+MIT License
+
+Copyright (c) 2022 Chair of Building Energy Systems and Heat Supply - TU Dresden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## What This Means
+
+The MIT License is a permissive open-source license that allows you to:
+
+✅ **Use** flixOpt for any purpose, including commercial applications
+✅ **Modify** the source code to fit your needs
+✅ **Distribute** copies of flixOpt
+✅ **Sublicense** under different terms
+✅ **Use privately** without making your modifications public
+
+## Contributing
+
+By contributing to flixOpt, you agree that your contributions will be licensed under the MIT License. See our [Contributing Guide](../contribute.md) for more information.