pyOpenSci Initial Review Cleanup

[JacksonBurns]

Feedback from Initial Submission to pyOpenSci

In the meanwhile I have a first question for you, if you don't mind.
While the statistical side of the package is clear and answers to a well known need of the scikit-learn user community, I would like to read a bit more about the package connections with chemical engineering. I guess your scientific application was the motivation for this development in the first place and in the documentation the two aspects look quite unrelated. Perhaps a small pedagogical section about chemical applications in the documentation will also be helpful? Thanks!

Originally posted by @cmarmo in pyOpenSci/software-submission#120 (comment)

We need to clarify the applications of astartes to chemical engineering in particular rather than just the importance in terms of statistics and ML, broadly speaking. As mentioned by @kspieks offline there is some content in the JOSS paper that could be pulled from to flesh this out.

I would suggest that we make a separate markdown document, like the 'sklearn to astartes' one and reference it in the main README.

[JacksonBurns]

Additional Comments:

(see here for full explanations)

References

Many references in the README are paywalled, try and find open-access versions. Some references are also missing, include them. Also make sure that the References column of the Included Sampling Algorithms table clarifies what the link actually is a reference to (documentation, a paper, etc.).

Formatting Fixes

External links with backquotes are breaking in the Sphinx rendered documentation.

Documentation

Add further examples of some of the backend, and how users could leverage other functionality implemented in astartes besides just train_(val_)test_split.

Version Attribute

Specify a __version__ attribute, as well as directions for how to retrieve it. Can use this to keep compatibility with pyproject.toml:

[project]
name = "astartes"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "package.__version__"}

Which is compatible with both from importlib.metadata import version and astartes.__version__ approaches.

[JacksonBurns]

All of this is done in #147 except for fixing the references and some documentation for the internal functions.