Full documentation review

[fwitte]

A full documentation review should be issued before the release of the next major version of TESPy. We will start the review the upcoming dev-meeting in December. Specific TODOs are listed below. I have added a short task description, feel free to comment/ask question. More specific information will be given at the dev-meeting.

workflow

0. If you did not fork oemof/tespy before:
   • fork tespy to your repositories
1. clone your repository
   • https: git clone https://github.com/YOURUSERNAME/tespy.git or use
   • ssh: git@github.com:YOURUSERNAME/tespy.git
2. if the branch oemof_doc_review is in your fork:
   • check out your oemof_doc_review branch (git checkout -b oemof_doc_review origin/oemof_doc_review)
3. Else:
   • create new local branch and pull from upstream (to add before).
   • git remote add upstream https://github.com/oemof/tespy.git
   • git checkout -b oemof_doc_review
   • git pull upstream/oemof_doc_review
4. push your adjustments to your remote branch (git push or git push --set-upstream origin oemof_doc_review)
5. create a PR on oemof/tespy to merge your remote branch in oemof/tespy oemof_doc_review
6. profit :)! (see https://github.com/oemof/oemof/pull/661)

documentation review

online documentation
In the online documentation we need to check for

• typos,

• comprehensibility (would a new user understand the main ideas?) and

• structure (does the structure of the chapters help the user understand how to use tespy?).

• README/Introduction

• Examples

• Tutorials

• Installation and setup

  • Revision
  • Add missing part for Mac

• Using TESPy

  • Introduction
  • networs and network reader
  • components
  • subsystems
  • connections
  • fluid properties

• What's New

  • add examples regarding API changes

doc-strings and inline comments
In the doc-strings and the inline comments we need to check for the following:

• Are there any typos?

• Are the examples comprehensible?

• Is information well placed (are the equations and parameters apparent)?

• Are the links in the doc-strings working?

• Are the inline comments clear?

• tespy/components/

  • components.py
  • turbomachinery.py
  • heat_exchangers.py
  • piping.py
  • combustion.py
  • reactors.py
  • nodes.py
  • subsystem_interfaces.py
  • subsystems.py

• tespy/tools/

  • helpers.py
  • fluid_properties.py
  • data_containers.py
  • characteristics.py

• tespy/connections/

  • connections.py
  • busses.py
  • refs.py

• tespy/networks/

  • networks.py
  • network_reader.py

[fwitte]

The online documentation review should be finished for the release of 0.2.0. Additionally the changes made in the API should be documented in the What's New section and the examples in the oemof_examples repository should be updated accordingly.

In the list above we will keep track, which parts have been reviewed.