search

JelteF / PyLaTeX

A Python library for creating LaTeX files
https://jeltef.github.io/PyLaTeX/
MIT License
2.27k stars 288 forks source link

Doctests #385

Closed Erotemic closed 3 months ago

Erotemic commented 3 months ago

First off, thank you for the library, it is a joy to use.

I was looking at the docstr for pylatex.Document in IPython and I found myself wishing that it had an example of a minimal use-case. I was able to look at the read the docs to get what I needed, but it would have been faster if it was builtin to the docstring itself. So I added a doctest that give a "hello world" example.

You'll note there I also added a "demo" section that gives a command line that will invoke the doctest, as well as a section at the end which uses my xdev package to actually pop the open the generated document for the user in whatever the default pdf program is. I think these are nice, but also not strictly necessary and it does require an extra dependency if you actually want to execute the doctest, so it could be paired down if desired.

However, I noticed that there were other doctests in the package, but it seems like they are never being run in CI and many of them are out of data and display incorrect results. I went through and fixed these. To ensure these don't break again I added the xdoctest package as a test-time dependency and included it in the testall.sh script, so now doctests will be run with the unit tests when invoking pytest. I also added a section to the pyproject.toml that does "the right thing" when the users just runs pytest in the repo root. There was also a minor issue with pytest attempting to pickup a __pycache__ directory that I fixed.

Lastly, there were a few deprecation warnings I saw in the test result. np.matrix is deprecated, so I replaced it with np.array. Also there were some backslashes that were not escaped correctly in two test files that I fixed.

Diff should be fairly clean and reviewable. Let me know what you think / if there are questions.

JelteF commented 3 months ago

Thank you for the work on this. I updated the github actions file so that it would also run CI for your PR. There seems to be some issue with your docstring though.

Erotemic commented 3 months ago

Looks like sphinx doesn't like the "Demo" tag I added, which I was iffy on anyway, so I just removed it. I think it will work now.