tespy Complete refurbishment of the documentation

Hi everyone,

I pushed the structure idea with the new template to this branch. You can have a look at the documentation here: https://tespy--355.org.readthedocs.build/en/355/contents.html

I'd love to get some feedback and suggestions on

the outline/structure
- Are the headlines clear to understand?
- Are you missing stuff?
- Is there too much stuff?
the template
- Are there elements and/or styles you'd like to change?
- Are features missing?
the landing page
- (not yet ready, but once it is): Do you find it appealing?

Looking forward to a fruitful discussion!

If you want to make changes yourselves, you are free to do so! There are two possible ways:

Directly push to this branch
Create a fork of the repo/update your fork to fetch the current state of this branch, make the changes there and open a pull request.

In any case, if you want to make changes, please reach out to me, if you have questions or trouble making and testing them. To create the documentation on your local machine for testing it before pushing the changes, you need to install tespy with the .[dev] flag:

conda activate your_tespy_environment
cd /paht/to/clone/of/tespy
pip install -e .[dev]

Then make the changes and render the documentation with

python -m sphinx ./docs/ ./docs/_build

A _build folder will appear in the docs folder, where you can open the contents.html page.

Thank you so much for your help :)

Aug 16 '22 16:08 fwitte

@ChaofanChen @nkawerau @andreas-sm @fgasa @maltefritz

I also added you to the oemof-tespy team, which allows you to directly push to or review this pull request by directly commenting on the code changes, if you like.

Aug 16 '22 17:08 fwitte

Looking good! I only took a hard look at the Installation and setup/Modeling basic systems, so far.

• the outline/structure o Are the headlines clear to understand? I think so. Capital Case on Installation and setup

o Are you missing stuff?

First steps: broken link to image 1; api/_images/intro_district_heating_scheme.svg
Start your calculation: broken link to image; api/_images/tutorial_heat_pump.svg

I will add more later.

Aug 22 '22 00:08 NicholasFry

Hey @fwitte,

first of all I really like the new documentation, because it is very appealing and clear. I have a few comments or improvements for you:

The introduction page of "Modeling Basic Systems" is very attractive and has a modern touch. It would be awesome if "Advanced Tutorial" and "Real World Applications" will have the same feature. In my opinon this function is not necessary in "TESPy modules". It seems to be a little bit overpowered.
In "API documentation" "tespy.components.module" are a lot content. It would be nice if it will be structured it as you do in "Component" in "TESPy modules".
Maybe you can add an example for creating a automatic model documentation in LATEX. The appropriate place would be in "Advanced tutorial" or in "Advanced Features".
The headline "Real World Applications" sounds unreachable. Maybe you can name it "Applications", "Examples" or something like this.
Finally, just a small note: The next "Online Stammtisch" will not take place in June. It will take place on September 19.

I hope my comments will help a little bit. Beste regards

Aug 24 '22 13:08 maltefritz

Thanks to both of you!

The introduction page of "Modeling Basic Systems" is very attractive and has a modern touch. It would be awesome if "Advanced Tutorial" and "Real World Applications" will have the same feature. In my opinon this function is not necessary in "TESPy modules". It seems to be a little bit overpowered.

Well it is started now, can be changed back at any time.

In "API documentation" "tespy.components.module" are a lot content. It would be nice if it will be structured it as you do in "Component" in "TESPy modules".

You mean with the list at the beginning?

Maybe you can add an example for creating a automatic model documentation in LATEX. The appropriate place would be in "Advanced tutorial" or in "Advanced Features".

Good idea, but it would not be on my priority list actually.

The headline "Real World Applications" sounds unreachable. Maybe you can name it "Applications", "Examples" or something like this.

Renamed to "Example Applications"

Finally, just a small note: The next "Online Stammtisch" will not take place in June. It will take place on September 19.

Will be 26th most likely, at least I do not have time on the 19th.

I hope my comments will help a little bit. Beste regards

Definitively, thank you!

1. First steps: broken link to image 1; api/_images/intro_district_heating_scheme.svg
   ![image](https://user-images.githubusercontent.com/60554125/185817372-42c3b28b-dc6b-442c-a28a-40197112cec9.png)

2. Start your calculation: broken link to image; api/_images/tutorial_heat_pump.svg
   ![image](https://user-images.githubusercontent.com/60554125/185817386-81008b2e-45a7-4e4d-9eac-5202bc266364.png)

Those will be fixed step by step once the respective section is finished.

Aug 24 '22 15:08 fwitte

Hello @fwitte! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

In the file tutorial/advanced/optimization_example.py:

Line 194:5: E125 continuation line with same indent as next logical line Line 230:1: E305 expected 2 blank lines after class or function definition, found 1 Line 269:1: E402 module level import not at top of file

In the file tutorial/advanced/starting_values.py:

Line 59:80: E501 line too long (81 > 79 characters) Line 60:80: E501 line too long (83 > 79 characters) Line 61:80: E501 line too long (87 > 79 characters) Line 117:1: E402 module level import not at top of file Line 157:1: E302 expected 2 blank lines, found 0 Line 191:80: E501 line too long (82 > 79 characters) Line 192:80: E501 line too long (80 > 79 characters) Line 205:80: E501 line too long (85 > 79 characters) Line 206:80: E501 line too long (87 > 79 characters) Line 207:80: E501 line too long (91 > 79 characters) Line 215:80: E501 line too long (81 > 79 characters) Line 276:9: E116 unexpected indentation (comment) Line 292:1: E305 expected 2 blank lines after class or function definition, found 0 Line 292:1: E402 module level import not at top of file Line 293:1: E402 module level import not at top of file

In the file tutorial/advanced/stepwise.py:

Line 10:1: E402 module level import not at top of file Line 11:1: E402 module level import not at top of file Line 12:1: E402 module level import not at top of file Line 13:1: E402 module level import not at top of file Line 14:1: E402 module level import not at top of file Line 15:1: E402 module level import not at top of file Line 27:1: E402 module level import not at top of file Line 43:1: E402 module level import not at top of file Line 55:1: E402 module level import not at top of file Line 105:1: E402 module level import not at top of file Line 186:1: E402 module level import not at top of file Line 187:1: E402 module level import not at top of file Line 207:1: E402 module level import not at top of file

In the file tutorial/basics/district_heating.py:

Line 79:1: E402 module level import not at top of file Line 80:1: E402 module level import not at top of file Line 123:80: E501 line too long (82 > 79 characters)

In the file tutorial/basics/gas_turbine.py:

Line 97:1: E402 module level import not at top of file Line 98:1: E402 module level import not at top of file

In the file tutorial/basics/heat_pump.py:

Line 11:1: E402 module level import not at top of file Line 25:1: E402 module level import not at top of file Line 75:1: E402 module level import not at top of file Line 76:1: E402 module level import not at top of file

In the file tutorial/basics/rankine.py:

Line 9:1: E402 module level import not at top of file Line 22:1: E402 module level import not at top of file Line 56:1: E402 module level import not at top of file Line 79:1: E402 module level import not at top of file Line 80:1: E402 module level import not at top of file

Comment last updated at 2022-09-07 07:38:48 UTC

Aug 28 '22 15:08 pep8speaks

This pull request introduces 2 alerts when merging 3c30e4a535b8b140b52ed31088eb93ef9f9ef2f4 into 968a2c2cb7b74522b6f4b3d289bdae1daa04cea7 - view on LGTM.com

new alerts:

2 for Unused import

Aug 28 '22 15:08 lgtm-com[bot]

This pull request introduces 2 alerts when merging 8d899272ddf0d2e01834d62105a05f9f16ca767b into 968a2c2cb7b74522b6f4b3d289bdae1daa04cea7 - view on LGTM.com

new alerts:

2 for Unused import

Aug 28 '22 16:08 lgtm-com[bot]

This pull request introduces 2 alerts when merging d35ab344f88186f93b98c1c947116d5733aa91c8 into 968a2c2cb7b74522b6f4b3d289bdae1daa04cea7 - view on LGTM.com

new alerts:

2 for Unused import

Aug 29 '22 18:08 lgtm-com[bot]

This pull request introduces 2 alerts when merging f93870a3957d6b0915fd28dd99b207e70bc50a09 into 968a2c2cb7b74522b6f4b3d289bdae1daa04cea7 - view on LGTM.com

new alerts:

2 for Unused import

Aug 30 '22 20:08 lgtm-com[bot]

This pull request introduces 2 alerts when merging a60ed16505082b3c4debd9b25b3ad35f5bf85e12 into 968a2c2cb7b74522b6f4b3d289bdae1daa04cea7 - view on LGTM.com

new alerts:

1 for Unused import
1 for Variable defined multiple times

Sep 03 '22 12:09 lgtm-com[bot]

Hi @fwitte,

thank you very much for the nice work on the refurbishment of the online document.

Only one comment from my side, it would be better to have a small section to present the highlight publication list or the projects using TESPy just like what OGS and Coolprop did.

Best regards, Chaofan

Sep 05 '22 20:09 ChaofanChen

@NicholasFry, @maltefritz, @ChaofanChen, @fgasa, @jfreissmann: Thank you for your feedback, rework is nearly done. I will present the new documentation on Monday, if anybody is interested (user meeting rescheduled from last Monday at 17:00 CEST).

Have a nice weekend, best!

Sep 24 '22 08:09 fwitte