Adding examples into function documentation

[matteobecchi]

It would be very nice to have an example of how to use each function, within the doc string of the function. The same way numpy does it.

It is already done for the LENS module, spatial_average() and the Shannon entropy functions. So it should be added in:

• radial_distribution_function
• onion (from the tropea-clustering package)
• time_soap
• soapify
• hdf5er

[andrewtarzia]

One comment I have for this is to use the testcode functionality in sphinx to make them small unit tests, ensuring their accuracy, for example, you can place the code below into the doc string:

    Examples:
        .. testcode:: dynsight-test

            import dynsight

            x = dynsight.calculate_something()

        .. testcode:: dynsight-test
            :hide:
        
            assert x == 'something you know'

[matteobecchi]

I modified, within tropea_clsutering, the doc strings of the functions imported by dynsight.onion, adding the examples.

When I run "just check" in tropea_clsutering, they are tested and work fine.

When I run "just check" in dynsight, some of the tests randomly fail, as if for some reason the random data used as input were changing. But the random seed is set, and there is no such issue in tropea_clustering.

[andrewtarzia]

When I run "just check" in dynsight, some of the tests randomly fail, as if for some reason the random data used as input were changing. But the random seed is set, and there is no such issue in tropea_clustering.

• Is it the same tests that fail? or is it actually random?
• are the environments (all numpy versions and such) the same?

[matteobecchi]

• Is it the same tests that fail? or is it actually random?

It's actually random. Sometimes one of the four functions fails the test. Sometimes none of them.

• are the environments (all numpy versions and such) the same?

There are many differences, among which numpy, Sphinx, ruff, scipy and scikit.learn. This could be the issue.

[matteobecchi]

Equating the packages used in tropea and dynsight, the issue is solved.