[MNT] testing code in README for correctness

[tschm]

• CI test job to test that code in README runs and is complete
• minor README reformatting and linting

[fkiraly]

Not sure what this is doing except adding >>> in front of code?

I do not see why we should do that.

Plus, you seem to be reformatting code so some lines do not fit on the screen anymore.
Maybe also let's not do this?

Plus my usual comments:

• please write a descriptive summary of your PR, I have a hard time understanding what you want to do here. Use AI if you need to, some description is better than none.
• where possible, do different things in separate PR, e.g., adding output coercion to portfolio_performance is not "test readme"

[tschm]

No, try to provoke the test with faulty code in README.md

[fkiraly]

?? I am sorry, I genuinely have no idea what you are referring to.

Can you please add a description to the PR and explain its purpose?

There should be no >>> at the start of the code in the readme.

[tschm]

Please ignore for now. Please read up on doctest

[fkiraly]

@tschm, I know how doctest works and have written doctest plugins for pytest myself.

Please don't assume lack of knowledge but provide an explanation or description what you are intending to do here.

Regarding doctest: the >>> are used to indicate code in a docstring. The docstring is then displayed without the >>>. Now you inserted >>> in the readme, which gets displayed including the >>>, so turns perfectly fine code into code with syntax error once users want to copy it.

[tschm]

I am not 100% sure on those >>>. I use them to indicate a doctest executable python command where as rows without them indicate the expected output (tested sign for sign). Yes, they make copy some inconvenient, but better than faulty code in a README...

[fkiraly]

Yes, they make copy some inconvenient

The entire point of the readme is to provide the most conveniently possible entry point to potential users. So I would strongly oppose any change that reduces user convenience substantially for a little bit of developer convenience.

Speaking about developer convenience, it is easy to get the python blocks. Just grep anything between triple-backtick-python and triple-backtick lines.
No need for a complicated abuse of doctest.

[fkiraly]

do I understand correctly, you want to test code in the README for correctness? (that it runs)

That would be a very useful CI step!

Though I would do it differently, and that avoids doing the business with the >>>:

• grep code blocks as the lines between triplebacktick-python and triplebacktick
• execute them in the test env

Done

[tschm]

@fkiraly I have managed to remove the >>> construct. All code blocks in README are merged into one big block and executed via subprocess. Each code block also comes with a result block. Those result blocks are merged and then the output is compared. No additional pytest-tools are needed. Please merge as your earliest convenience...

[fkiraly]

Looks like the idea works!

Thanks!