Skip to content

Commit 4bf5cfc

Browse files
FBumannFBumann
authored
Feature/improve docs (#449)
* Improve docs * Improve docs * Improve docs and fix links * Update contribute.md * Update contribute.md * Improve CONTRIBUTE.md * Update CHANGELOG.md
1 parent 3e9839b commit 4bf5cfc

9 files changed

Lines changed: 154 additions & 70 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
7272
### 📦 Dependencies
7373
7474
### 📝 Docs
75+
- Add more comprehensive `CONTRIBUTE.md`
76+
- Improve logical structure in User Guide
7577
7678
### 👷 Development
7779

‎CONTRIBUTE.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to FlixOpt
2+
3+
We warmly welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing examples, your contributions are valuable.
4+
5+
## Ways to Contribute
6+
7+
### 🐛 Report Issues
8+
Found a bug or have a feature request? Please [open an issue](https://github.com/flixOpt/flixopt/issues) on GitHub.
9+
10+
When reporting issues, please include:
11+
- A clear description of the problem
12+
- Steps to reproduce the issue
13+
- Expected vs. actual behavior
14+
- Your environment (OS, Python version, FlixOpt version)
15+
- Minimal code example if applicable
16+
17+
### 💡 Share Examples
18+
Help others learn FlixOpt by contributing examples:
19+
- Real-world use cases
20+
- Tutorial notebooks
21+
- Integration examples with other tools
22+
- Add them to the `examples/` directory
23+
24+
### 📖 Improve Documentation
25+
Documentation improvements are always welcome:
26+
- Fix typos or clarify existing docs
27+
- Add missing documentation
28+
- Translate documentation
29+
- Improve code comments
30+
31+
### 🔧 Submit Code Contributions
32+
Ready to contribute code? Great! See the sections below for setup and guidelines.
33+
34+
---
35+
36+
## Development Setup
37+
38+
### Getting Started
39+
1. Fork and clone the repository:
40+
```bash
41+
git clone https://github.com/flixOpt/flixopt.git
42+
cd flixopt
43+
```
44+
45+
2. Install development dependencies:
46+
```bash
47+
pip install -e ".[full, dev]"
48+
```
49+
50+
3. Set up pre-commit hooks (one-time setup):
51+
```bash
52+
pre-commit install
53+
```
54+
55+
4. Verify your setup:
56+
```bash
57+
pytest
58+
```
59+
60+
### Working with Documentation
61+
FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation.
62+
63+
To work on documentation:
64+
```bash
65+
pip install -e ".[docs]"
66+
mkdocs serve
67+
```
68+
Then navigate to http://127.0.0.1:8000/
69+
70+
---
71+
72+
## Code Quality Standards
73+
74+
### Automated Checks
75+
We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**.
76+
77+
### Manual Checks
78+
To run checks manually:
79+
- `ruff check --fix .` - Check and fix linting issues
80+
- `ruff format .` - Format code
81+
- `pre-commit run --all-files` - Run all pre-commit checks
82+
83+
### Testing
84+
- `pytest` - Run the test suite
85+
- Ensure all tests pass before submitting a PR
86+
87+
### Coding Guidelines
88+
- Follow [PEP 8](https://pep8.org/) style guidelines
89+
- Write clear, self-documenting code with helpful comments
90+
- Include type hints for function signatures
91+
- Create or update tests for new functionality
92+
- Aim for 100% test coverage for new code
93+
94+
---
95+
96+
## Workflow
97+
98+
### Branches & Pull Requests
99+
1. Create a feature branch from `main`:
100+
```bash
101+
git checkout -b feature/your-feature-name
102+
```
103+
104+
2. Make your changes and commit them with clear messages
105+
106+
3. Push your branch and open a Pull Request
107+
108+
4. Ensure all CI checks pass
109+
110+
### Branch Naming
111+
- Features: `feature/feature-name`
112+
- Bug fixes: `fix/bug-description`
113+
- Documentation: `docs/what-changed`
114+
115+
### Commit Messages
116+
- Use clear, descriptive commit messages
117+
- Start with a verb (Add, Fix, Update, Remove, etc.)
118+
- Keep the first line under 72 characters
119+
120+
---
121+
122+
## Releases
123+
124+
We follow **Semantic Versioning** (MAJOR.MINOR.PATCH). Releases are created manually from the `main` branch by maintainers.
125+
126+
---
127+
128+
## Questions?
129+
130+
If you have questions or need help, feel free to:
131+
- Open a discussion on GitHub
132+
- Ask in an issue
133+
- Reach out to the maintainers
134+
135+
Thank you for contributing to FlixOpt!

‎docs/contribute.md‎

Lines changed: 1 addition & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1 @@
1-
# Contributing to the Project
2-
3-
We warmly welcome contributions from the community! This guide will help you get started with contributing to our project.
4-
5-
## Development Setup
6-
1. Clone the repository `git clone https://github.com/flixOpt/flixopt.git`
7-
2. Install the development dependencies `pip install -e ".[dev]"`
8-
3. Install pre-commit hooks `pre-commit install` (one-time setup)
9-
4. Run `pytest` to ensure your code passes all tests
10-
11-
## Code Quality
12-
We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**.
13-
14-
To run manually:
15-
- `ruff check --fix .` to check and fix linting issues
16-
- `ruff format .` to format code or
17-
- `pre-commit run` or `pre-commit run --all-files` to trigger all checks
18-
19-
## Documentation (Optional)
20-
FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation.
21-
To work on documentation:
22-
```bash
23-
pip install -e ".[docs]"
24-
mkdocs serve
25-
```
26-
Then navigate to http://127.0.0.1:8000/
27-
28-
## Testing
29-
- `pytest` to run the test suite
30-
- You can also run the provided python script `run_all_test.py`
31-
32-
---
33-
# Best practices
34-
35-
## Coding Guidelines
36-
37-
- Follow PEP 8 style guidelines
38-
- Write clear, commented code
39-
- Include type hints
40-
- Create or update tests for new functionality
41-
- Ensure 100% test coverage for new code
42-
43-
## Branches & Releases
44-
New features should be branched from `main` into `feature/*`
45-
As stated, we follow **Semantic Versioning**. Releases are created manually from the `main` branch.
1+
{! ../CONTRIBUTE.md !}

‎docs/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,6 @@ Working with FlixOpt follows a general pattern:
3737

3838
Now that you've installed FlixOpt and understand the basic workflow, you can:
3939

40-
- Learn about the [core concepts of FlixOpt](user-guide/index.md)
40+
- Learn about the [core concepts of flixopt](user-guide/core-concepts.md)
4141
- Explore some [examples](examples/index.md)
4242
- Check the [API reference](api-reference/index.md) for detailed documentation

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,6 @@ Help improve FlixOpt by contributing code, docs, or examples
139139

140140
{%
141141
include-markdown "../README.md"
142-
start="## Installation"
143-
end="## License"
142+
start="## 🛠️ Installation"
143+
end="## 📄 License"
144144
%}

docs/user-guide/index.md renamed to docs/user-guide/core-concepts.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# FlixOpt Concepts
1+
# Core concepts of flixopt
22

33
FlixOpt is built around a set of core concepts that work together to represent and optimize **any system involving flows and conversions** - whether that's energy systems, material flows, supply chains, water networks, or production processes.
44

55
This page provides a high-level overview of these concepts and how they interact.
66

7-
## Core Concepts
7+
## Main building blocks
88

99
### FlowSystem
1010

@@ -121,19 +121,20 @@ This [`CalculationResults`][flixopt.results.CalculationResults] object can be sa
121121
The process of working with FlixOpt can be divided into 3 steps:
122122

123123
1. Create a [`FlowSystem`][flixopt.flow_system.FlowSystem], containing all the elements and data of your system
124-
- Define the time series of your system
125-
- Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc.
126-
- Add [`Buses`][flixopt.elements.Bus] as connection points in your system
124+
- Define the time horizon of your system (and optionally your periods and scenarios, see [Dimensions](mathematical-notation/dimensions.md)))
127125
- Add [`Effects`][flixopt.effects.Effect] to represent costs, emissions, etc.
128-
- *This [`FlowSystem`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file*
126+
- Add [`Buses`][flixopt.elements.Bus] as connection points in your systeand [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
127+
- Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc.
128+
- Add
129+
- [`FlowSystems`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file*
129130
2. Translate the model to a mathematical optimization problem
130131
- Create a [`Calculation`][flixopt.calculation.Calculation] from your FlowSystem and choose a Solver
131-
- ...The Calculation is translated internaly to a mathematical optimization problem...
132+
- ...The Calculation is translated internally to a mathematical optimization problem...
132133
- ...and solved by the chosen solver.
133134
3. Analyze the results
134135
- The results are stored in a [`CalculationResults`][flixopt.results.CalculationResults] object
135136
- This object can be saved to file and reloaded from file, retaining all information about the calculation
136-
- As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it can be used to start a new calculation
137+
- As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it fully documents all assumptions taken to create the results.
137138

138139
<figure markdown>
139140
![FlixOpt Conceptual Usage](../images/architecture_flixOpt.png)

‎docs/user-guide/mathematical-notation/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11

22
# Mathematical Notation
33

4-
This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../index.md) guide.
4+
This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../core-concepts.md) guide.
55

6-
**For typical usage**, refer to the [FlixOpt Concepts](../index.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively.
6+
**For typical usage**, refer to the [FlixOpt Concepts](../core-concepts.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively.
77

88
---
99

‎mkdocs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ repo_name: flixOpt/flixopt
1111
nav:
1212
- Home: index.md
1313
- User Guide:
14-
- user-guide/index.md
15-
- Migration to v3.0.0: user-guide/migration-guide-v3.md
1614
- Getting Started: getting-started.md
15+
- Core Concepts: user-guide/core-concepts.md
16+
- Migration to v3.0.0: user-guide/migration-guide-v3.md
1717
- Mathematical Notation:
1818
- Overview: user-guide/mathematical-notation/index.md
1919
- Dimensions: user-guide/mathematical-notation/dimensions.md

‎tests/run_all_tests.py‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

0 commit comments

Comments
 (0)