Complete refurbishment of the documentation

fwitte commented 1 year ago

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 :)

fwitte commented 1 year ago

@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.

NicholasFry commented 1 year ago

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.

maltefritz commented 1 year ago

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

fwitte commented 1 year ago

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.

pep8speaks commented 1 year ago

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