Suggested changes for the documentation

General

I think combining mixture property estimation with the ability to model reactions may be a highlight of this package, too. Maybe consider adding it to the highlights section on the landing page.
For rather inexperienced users who want to use the git version, you may add
```
$ cd thermosteam
$ pip install -e .
```
to your installation instructions.
Include a changelog, so the user is informed about the changes since the last (major) version. Maybe there are adjustments to perform in the code.
Add some comments on how to contribute to your project including instructions on testing.
Not a required change, but a hint: Sometimes an internal link is very useful, e.g. in the Note-box of the Chemical API documentation. You can establish a link to classes/subpackages/methods/... using :py:class:/:py:mod:/:py:meth:/..., see https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects.

Typos and rendering issues

In the middle of 3.8, I think "vle" or something is missing between "in" and "is". "Again, the most convinient way to get and set flow rates in is through the get_flow and set_flow methods:"
In 4.3 there is a space missing between "following:" and "T": "... from the following:T (temperature ..."
End of 4.3: I am not a native English speaker, but this does sound strange to me "Here we are some examples of the possibilities:".
Adding a process overview diagram at the beginning of chapter 5 (or 6) would be very good to better comprehend the context for a new user.
In 5.3 it should be "factors" instead of "factos".
Are the first lines of chapter 6 meant to be printed bold?
At the very end of chapter 6.4. it should be ReactionItem instead of "ReationItem" and conversion instead of "converion". I too get hectic, when seeing the finish line sometimes :D.
The list at https://github.com/BioSTEAMDevelopmentGroup/thermosteam/blob/master/thermosteam/_multi_stream.py#L162-L167 is not rendered correctly, there must be an empty line before the list.
Examples header does not render correctly: https://thermosteam.readthedocs.io/en/latest/functional.html#thermosteam.functional.mixing_simple. Also, some mathematical formulas in this module do not render. I think, you need to have an empty line between the .. math:: statement and the actual formula (at least that's how I use it).
Is a word missing in the first line of https://thermosteam.readthedocs.io/en/latest/reaction/Reaction.html#thermosteam.reaction.Reaction?
The example in https://thermosteam.readthedocs.io/en/latest/_modules/thermosteam/separations.html#material_balance is not rendered. There must be an empty line after "Satisfy outlet flows:".
Do you write "i.e." with a space? In the Notes of https://thermosteam.readthedocs.io/en/latest/mixture/Mixture.html#thermosteam.mixture.Mixture.

Command-line execution of code instead of ipynb

I think you should mention to the users, that the tutorial shown is run in an ipynb and to have the same results in script based programs, some modifications are to be made:

Using the print() method instead in command-line execution of your code does not look beautiful in many instances, e.g.

print(pretreatment_parallel_rxn[0:2])

which prints as

ParallelReaction(["ReactionItem('Water + Glucan -> Glucose', reactant='Glucan', X=0.099, basis=mol), ReactionItem('Water + Glucan -> GlucoseOligomer', reactant='Glucan', X=0.003, basis=mol)"])

I suggest to give a hint to the user, that using

pretreatment_parallel_rxn[0:2].show()

behaves the same as the ipynb on readthedocs:

ParallelReaction (by mol):
index  stoichiometry                      reactant    X[%]
[0]    Water + Glucan -> Glucose          Glucan      9.90
[1]    Water + Glucan -> GlucoseOligomer  Glucan      0.30

To show plots the user must import matplotlib.pyplot, e.g.

import thermosteam as tmo
from matplotlib import pyplot as plt
Water = tmo.Chemical('Water')
Water.Psat.plot_vs_T([Water.Tm, Water.Tb], 'degC', 'atm', label="Water")
plt.show()

Thanks for reviewing the documentation in detail. It has lead to significant improvements. I'm addressing each point separately so that it is easy to follow:

General

I think combining mixture property estimation with the ability to model reactions may be a highlight of this package, too. Maybe consider adding it to the highlights section on the landing page.
- Agreed! Thermosteam's capabilities with stoichiometric reactions are noteworthy. The first sentence of the homepage now reads "Thermosteam is a standalone thermodynamic engine capable of estimating mixture properties, solving thermodynamic phase equilibria, and modeling stoichiometric reactions."
For rather inexperienced users who want to use the git version, you may add
```
$ cd thermosteam
$ pip install -e .
```
to your installation instructions.
- Good point, it's been added (https://thermosteam.readthedocs.io/en/latest/Installation.html)
Include a changelog, so the user is informed about the changes since the last (major) version. Maybe there are adjustments to perform in the code.
- I have been putting this off for some time. This is quite important, thanks for noting. It has been added (https://thermosteam.readthedocs.io/en/latest/updates/2.22.html). I'm starting from 0.22.1 and including some recent changes from 0.21. If you would like to make any comments on this, they are welcome!
Add some comments on how to contribute to your project including instructions on testing.
- Added! https://thermosteam.readthedocs.io/en/latest/CONTRIBUTING.html
Not a required change, but a hint: Sometimes an internal link is very useful, e.g. in the Note-box of the Chemical API documentation. You can establish a link to classes/subpackages/methods/... using :py:class:/:py:mod:/:py:meth:/..., see https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects.
- Got it, thanks for sharing. I may add this in the near future, but after the review. It would take me sometime to make the changes thoroughly.

Typos and rendering issues

In the middle of 3.8, I think "vle" or something is missing between "in" and "is". "Again, the most convinient way to get and set flow rates in is through the get_flow and set_flow methods:"
- Fixed! https://thermosteam.readthedocs.io/en/latest/tutorial/An_hour_blitz_to_practical_thermodynamics.html#Vapor-liquid-equilibrium
In 4.3 there is a space missing between "following:" and "T": "... from the following:T (temperature ..."
- Fixed! https://thermosteam.readthedocs.io/en/latest/tutorial/Thermodynamic_equilibrium.html#Vapor-liquid-equilibrium
End of 4.3: I am not a native English speaker, but this does sound strange to me "Here we are some examples of the possibilities:".
- Its super weird, good catch (fixed).
Adding a process overview diagram at the beginning of chapter 5 (or 6) would be very good to better comprehend the context for a new user.
- I think users would appreciate it too. I added a process diagram and made a better description. https://thermosteam.readthedocs.io/en/latest/tutorial/Thermo_property_packages.html
In 5.3 it should be "factors" instead of "factos".
- Fixed! https://thermosteam.readthedocs.io/en/latest/tutorial/Thermo_property_packages.html#Thermo-objects
Are the first lines of chapter 6 meant to be printed bold?
- They were meant to, but looking back, it looks awful. I removed the bold and edited the text. https://thermosteam.readthedocs.io/en/latest/tutorial/Stoichiometric_reactions.html#Stoichiometric-reactions
At the very end of chapter 6.4. it should be ReactionItem instead of "ReationItem" and conversion instead of "converion". I too get hectic, when seeing the finish line sometimes :D.
- Can't help it, jaja. Fixed! https://thermosteam.readthedocs.io/en/latest/tutorial/Stoichiometric_reactions.html#Indexing-reactions
The list at https://github.com/BioSTEAMDevelopmentGroup/thermosteam/blob/master/thermosteam/_multi_stream.py#L162-L167 is not rendered correctly, there must be an empty line before the list.
- Fixed!
Examples header does not render correctly: https://thermosteam.readthedocs.io/en/latest/functional.html#thermosteam.functional.mixing_simple. Also, some mathematical formulas in this module do not render. I think, you need to have an empty line between the .. math:: statement and the actual formula (at least that's how I use it).
- Fixed!
Is a word missing in the first line of https://thermosteam.readthedocs.io/en/latest/reaction/Reaction.html#thermosteam.reaction.Reaction?
- I'm not too sure what was I going for in that sentence, but it has been corrected to "A Reaction object is capable of reacting the material flow rates of a thermosteam.Stream object."
The example in https://thermosteam.readthedocs.io/en/latest/_modules/thermosteam/separations.html#material_balance is not rendered. There must be an empty line after "Satisfy outlet flows:".
- Good catch! Fixed.
Do you write "i.e." with a space? In the Notes of https://thermosteam.readthedocs.io/en/latest/mixture/Mixture.html#thermosteam.mixture.Mixture.
- Apparently sometimes I do (Fixed).

Command-line execution of code instead of ipynb

I think you should mention to the users, that the tutorial shown is run in an ipynb and to have the same results in script based programs, some modifications are to be made:
- Using the print() method instead in command-line execution of your code does not look beautiful in many instances, e.g.
```
print(pretreatment_parallel_rxn[0:2])
```
  which prints as
```
ParallelReaction(["ReactionItem('Water + Glucan -> Glucose', reactant='Glucan', X=0.099, basis=mol), ReactionItem('Water + Glucan -> GlucoseOligomer', reactant='Glucan', X=0.003, basis=mol)"])
```
I suggest to give a hint to the user, that using
```
pretreatment_parallel_rxn[0:2].show()
```
behaves the same as the ipynb on readthedocs:
```
ParallelReaction (by mol):
index  stoichiometry                      reactant    X[%]
[0]    Water + Glucan -> Glucose          Glucan      9.90
[1]    Water + Glucan -> GlucoseOligomer  Glucan      0.30
```
- To show plots the user must import matplotlib.pyplot, e.g.
```
import thermosteam as tmo
from matplotlib import pyplot as plt
Water = tmo.Chemical('Water')
Water.Psat.plot_vs_T([Water.Tm, Water.Tb], 'degC', 'atm', label="Water")
plt.show()
```
  Reply: Yes, I realize many people do not use ipython consoles (like in Spyder and Jupyter Notebook). I updated all the tutorials to use .show methods to be more explicit about this. I did not add a note as some people might miss it. I also added the matplotlib and plt.show() lines as you suggested.

Feel free to close this issue if I have addressed all your points. You're also welcome to make more comments on the documentation here too.

BioSTEAMDevelopmentGroup / thermosteam