Chempy documentation issues

[jdpipe]

I have been playing around with chempy and I can see that it provides quite a convenient way to solve some common and repetitious calculations.

However I think that the documentation content and structure could be greatly improved. For example, I went looking for an introduction to the Substance class. Starting from the home page, https://pythonhosted.org/chempy/index.html, searching for the word Substance doesn't lead you to any useful documentation. This is a really core class and somehow needs to be more clearly visible in the structure of the documentation. Similarly the class Equlibrium. One strategy would be to include a short paragraph before the introductory examples mentioning the classes/functions being used, and giving links to the documentation for each one.

Another point is that it's quite hard to figure out how to find the molecular mass of a substance. The documentation really doesn't support one to find that information. Searching for "molecular mass" doesn't get you anywhere useful. Searching for "molar mass" gets you what you need. The documentation for "mass" (Substance.mass) is not really clear -- what is 'data['mass']' and where is the documentation about that? I was a bit surprised that there is no convenience function like MolarMass('C2H5OH') being provided.

A key gap in the chempy package is around property data, which means that reaction enthalpy etc cannot be calculated. Perhaps the main documentation page or overview could provide a little detail around what is not covered in chempy, as well, to help the new user to understand its scope and limitations. Related python packages (eg Cantera) could perhaps be noted.

I know that documentation is a pain to write, but I think that this library would help lots of students if it could be made a bit easier to find the descriptions of some of the key features and how they should be used.

[bjodah]

Thank you John for reporting this. And yes, I do agree that there are plenty of things to improve in the documentation, and I agree with your suggestions. Hopefully we will find the time to improve on it going forward.

[linusable]

Firstly i would like to thank all contributors of the ChemPy library.

Concerning the documentation, i had to introduce the subject to students using either Windows or MacOS (i personnaly use GNU/Linux). They encounter some difficulties to install the ChemPy library with the Anaconda Distribution from its navigator.

Some students directly try the conda command. Thus it would be interesting to place before and emphasized the sentence "currently conda packages are only provided for Linux".

Secondly, the pip subcommand is right but must be invoked with "python" instead of "python3" command. I just try this today with a relatively fresh install of win10.

I will appreciate you adapt the documentation following this comment.

[bjodah]

Hi @linusable , glad to hear that ChemPy is of use. Would you mind opening a pull request with your suggested changes? (you can even edit README.rst directly in the web GUI). Thanks!

[chicolucio]

Hello!

I'm working on a project called Chemistry Programming, where I cover Python packages applied in chemistry. I've recently published a blog post about balancing chemical equations using ChemPy, which can be found here. I believe these examples and the text explaining them could be beneficial for the ChemPy documentation if you want to add or cite. Additionally, I plan to cover more ChemPy features in future posts. Please let me know if you think that any part of this material can be added to the docs. I would be glad to help.