chore: resolve doctest issues

[nathanwn]

While reading through some code, I realized the examples in some docstrings are wrong. These should have been caught by doctest.

Currently in pyproject.toml, pytest is configured as follows:

[tool.pytest.ini_options]
addopts = "--verbose --doctest-modules -ra --cov macaron"  # Consider adding --pdb
testpaths = [
    "tests",
]

Although the --doctest-modules flag is enabled, meaning doctest should run, testpaths is limited to only the tests directory. This does not allow doctest to pick up the docstring examples in src/macaron.

In this PR, I enable doctest to discover docstring examples in src/macaron as follows:

testpaths = [
+   "src/macaron",  # this is included to run doctest on examples
    "tests",
]

I also fix cases where the example fails doctest. There are commonly two reasons why these examples fail:

• Case 1: The example is wrong. One or more of these things happen: the test is syntactically wrong, or the input is wrong, or the output is wrong. In these cases, I fix the example.
• Case 2: The example is only intended to demonstrate how the API looks like, and not how it is actually used and what the corresponding result should be. In addition, the setup required for some of these examples is quite complex (e.g. requires loading a config or making an HTTP request). In these cases, I convert the example from using a Python REPL block, which is what doctest picks up, to using a Python code block.

[tromai]

Thanks for having a look @nathanwn . LGTM.