Feature/improve docs

[FBumann]

Description

Improve the docs by restructuring them a bit.

Type of Change

• Bug fix
• New feature
• Documentation update
• Code refactoring

Related Issues

Closes #(issue number)

Testing

• I have tested my changes
• Existing tests still pass

Checklist

• My code follows the project style
• I have updated documentation if needed
• I have added tests for new functionality (if applicable)

Summary by CodeRabbit

Release Notes

• Documentation
  • Added comprehensive contributor guidelines covering development setup, coding standards, and workflow.
  • Reorganized User Guide with clearer core concepts documentation.
  • Updated documentation navigation structure for improved consistency.
  • Enhanced clarity in foundational concepts and system component descriptions.

[coderabbitai]

Walkthrough

This PR reorganizes the documentation structure and introduces a new contributor guide. It renames the user guide index page to core-concepts.md, updates all related navigation entries and cross-references, delegates the contribute documentation through an include directive, and removes the standalone test runner script.

Changes

Cohort / File(s)	Summary
Documentation Navigation and Structure mkdocs.yml, docs/index.md, docs/contribute.md	Updated mkdocs navigation to replace user-guide/index.md with user-guide/core-concepts.md, modified include-markdown boundaries with emoji-prefixed markers, and delegated contribution docs via include directive.
Contributor Guide CONTRIBUTE.md	New comprehensive contributor guide documenting contribution methods, development setup, code quality standards, testing, coding guidelines, workflow conventions, and release practices.
User Guide Restructuring docs/getting-started.md, docs/user-guide/core-concepts.md, docs/user-guide/mathematical-notation/index.md	Renamed core concepts section, restructured FlowSystem overview with updated component descriptions, fixed typos, updated cross-reference links to point to new core-concepts page.
Project Maintenance CHANGELOG.md	Added documentation-related entries under Docs section.
Test Infrastructure tests/run_all_tests.py	Removed entire test runner script file.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Navigation coherence: Verify that all internal links (docs/getting-started.md, docs/user-guide/mathematical-notation/index.md, mkdocs.yml) correctly reference the renamed core-concepts.md page
• Include directive syntax: Confirm the include directive in docs/contribute.md ({! ../CONTRIBUTE.md !}) is compatible with the mkdocs processor
• Content completeness: Review CONTRIBUTE.md for accuracy and completeness of development setup instructions, workflow guidance, and best practices
• Section boundaries: Validate that emoji-prefixed markers in docs/index.md correctly capture the intended README content segments

Possibly related PRs

• Feature/readme and vision #405: Modifies mkdocs.yml and related documentation content/structure for navigation changes
• Feature/pretty docs with theme #413: Directly overlaps with modified docs/index.md and mkdocs.yml files
• Reogranize Docs #377: Includes overlapping documentation restructuring and user-guide reorganization

Suggested labels

v3.0.0

Poem

🐰 The docs now flow with structure bright,
From index renamed, core concepts take flight,
A contributor's path is clearly laid,
With navigation rebuilt, new foundations made! ✨

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description follows the template structure but has significant gaps in critical sections. The "Description" field states "Improve the docs by restructuring them a bit," which is too vague and doesn't explain what was specifically restructured or why. The "Related Issues" section shows an unfilled placeholder, and the "Testing" section is completely empty with no checkboxes marked. While the "Type of Change" is correctly selected and the checklist is marked complete, the lack of detail in the description section and the unfilled Related Issues field make it difficult for reviewers to understand the scope and context of these documentation changes.	Please improve the description by providing specific details: explain what was restructured (e.g., "moved contributing guide to root, reorganized user guide sections, updated navigation in mkdocs.yml"), fill in the Related Issues field with an actual issue number if applicable, and address the Testing section by either checking the relevant boxes or noting why testing wasn't needed for this documentation-only change.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title Check	❓ Inconclusive	The PR title "Feature/improve docs" is related to the changeset since the primary changes involve documentation restructuring, including reorganizing the user guide, adding a contributor guide, and updating navigation. However, the title is quite generic and vague—it uses the broad term "improve docs" without specifying what aspects were improved or that this was primarily a restructuring effort. While it's not entirely uninformative like "misc updates," it falls short of clearly conveying the specific nature of the changes to someone scanning the commit history.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/improve-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[FBumann]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

CONTRIBUTE.md (1)

83-92: Consider expanding testing guidance.

The testing section (lines 83-85) is concise but could benefit from a bit more detail. Consider adding guidance on:

• Where to add tests (e.g., tests/ directory structure)
• Common test patterns in the project
• How to run specific test suites or individual tests

This would help contributors more effectively navigate the testing workflow.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2b2e835 and 707031b.

📒 Files selected for processing (9)

• CHANGELOG.md (1 hunks)
• CONTRIBUTE.md (1 hunks)
• docs/contribute.md (1 hunks)
• docs/getting-started.md (1 hunks)
• docs/index.md (1 hunks)
• docs/user-guide/core-concepts.md (2 hunks)
• docs/user-guide/mathematical-notation/index.md (1 hunks)
• mkdocs.yml (1 hunks)
• tests/run_all_tests.py (0 hunks)

💤 Files with no reviewable changes (1)

• tests/run_all_tests.py

🧰 Additional context used

🪛 LanguageTool

docs/user-guide/core-concepts.md

[grammar] ~126-~126: Ensure spelling is correct
Context: ...ments.Bus] as connection points in your systeand [Sinks][flixopt.components.Sink] & [`...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (8)

CHANGELOG.md (1)

84-85: LGTM!

The changelog entries accurately reflect the documentation restructuring work in this PR.

docs/user-guide/mathematical-notation/index.md (1)

4-4: Cross-references correctly updated.

The links to ../core-concepts.md are consistent with the documentation restructuring and align with the mkdocs.yml navigation changes.

Also applies to: 6-6

docs/user-guide/core-concepts.md (1)

1-1: Documentation restructuring looks good overall.

The renaming from "FlixOpt Concepts" to "Core concepts of flixopt" better reflects the page's position as a foundational guide. The Step 1 content has been expanded to clarify system-building steps, and the mention of netCDF loading has been appropriately repositioned. The typo noted above aside, the restructuring enhances clarity.

Also applies to: 7-7, 124-137

docs/getting-started.md (1)

40-40: Link correctly updated.

The reference to the core concepts guide is consistent with the documentation restructuring and mkdocs.yml navigation changes.

mkdocs.yml (1)

15-16: Navigation structure updated appropriately.

The explicit "Core Concepts" entry provides better navigation clarity than using an index file. The placement and hierarchy are consistent with the documentation restructuring.

docs/contribute.md (1)

1-1: Documentation delegation is clean and maintainable.

Using the include directive to delegate to the root CONTRIBUTE.md file is an excellent DRY pattern. The include-markdown plugin is already configured in mkdocs.yml (line 190), so this will work seamlessly.

CONTRIBUTE.md (1)

1-135: Excellent comprehensive contribution guide.

The CONTRIBUTE.md provides clear, actionable guidance covering issue reporting, examples, documentation, and code contributions. The development setup instructions are practical with concrete commands. The code quality standards (ruff formatting, PEP8, type hints, 100% test coverage) are well-defined and professionally presented.

docs/index.md (1)

142-143: Section headers verified in README.md.

The verification confirms that README.md contains both required section headers:

• ## 🛠️ Installation at line 147
• ## 📄 License at line 190

The include-markdown markers in docs/index.md (lines 142-143) correctly reference these headers.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix typo in line 126.

There is a spelling error: "systeand" should be "system and".

Apply this diff:

-     -  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, ...)
+     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your system and [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- 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, ...)
	- Add [`Buses`][flixopt.elements.Bus] as connection points in your system and [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)

🧰 Tools

🪛 LanguageTool

[grammar] ~126-~126: Ensure spelling is correct
Context: ...ments.Bus] as connection points in your systeand [Sinks][flixopt.components.Sink] & [`...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents

In docs/user-guide/core-concepts.md around line 126, there's a typo: replace the
word "systeand" with "system and" so the sentence reads "Add
[`Buses`][flixopt.elements.Bus] as connection points in your system and
[`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as
connections to the outer world (markets, power grid, ...)".