JOSS Review--Documentation

[yuxuanzhuang]

This is part of the review process for openjournals/joss-reviews#6295

Great work!! I've noticed a few minor issues that could be addressed:

• In https://pyeql.readthedocs.io/en/latest/, s1 = pyEQL.Solution -> s1 = Solution().

• In https://pyeql.readthedocs.io/en/latest/chemistry.html#how-to-enter-valid-chemical-formulas:

  • The word "interpret" is misspelled as "inerpret."
  • The chemical formula for Sodium Sulfate should beNa2SO4.

• In https://pyeql.readthedocs.io/en/latest/mixing.html, there is an issue with an equation not being shown correctly.

• In https://pyeql.readthedocs.io/en/latest/class_solution.html and https://pyeql.readthedocs.io/en/latest/internal.html have rendering problems

  • Not all Return is displayed correctly.
  • Examples do not appear correctly.
  • Links in the see also sections are not functioning as expected.

[rkingsbury]

Thank you for reporting @yuxuanzhuang !

[rkingsbury]

Reproducing here some additional comments from the JOSS review related to Docs cleanups:

List of some small things:

• the ending copyright year on the license (2023) is now outdated
• I think you are missing an @ in your paper on this line:

  pyEQL/docs/joss/paper.md

  Line 66 in fd35750

  parameters [@May2011b] for more than 100 salts, diffusion coefficients [CRCdiffusion] for more than 100 solutes,

  
  - There is an extra ::: on this line of the docs:

  pyEQL/docs/contributing.md

  Line 11 in c43b2e6

  :::{tip} Please don't forget to include the closed issues in your search. Sometimes a solution was already reported, and the problem is considered solved. :::

  
  - Might be missing a hyperlink on this line of the docs for [Sphinx] (?):

  pyEQL/docs/contributing.md

  Line 20 in c43b2e6

  `pyEQL` documentation uses [Sphinx] as its main documentation compiler.

  
  - The sections of code and text in the contributing page are flipped from this line onwards:

  pyEQL/docs/contributing.md

  Line 47 in c43b2e6

  When working on documentation changes in your local machine, you can

  so it renders like this: