pytester is lacking documentation

[wimglenn]

docs: https://docs.pytest.org/en/latest/reference.html#_pytest.pytester.Testdir

source: https://docs.pytest.org/en/latest/_modules/_pytest/pytester.html#Testdir

Many important methods missing from the docs, such as makeini.

[nicoddemus]

Hi @wimglenn thanks for the report.

Indeed pytester docs is declared in the reference listing the members explicitly:

.. autoclass:: Testdir()
    :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile

I think it could be changed to just :members: so it will list all public members instead.

Would you like to contribute a PR?

[wimglenn]

OK, I've created the PR. Hit a few roadblocks on the way. Removing the :members: caused the docs build to fail:

Warning, treated as error:
/Users/wim/src/pytest/src/_pytest/pytester.py:docstring of _pytest.pytester.Testdir.makefile:13:Block quote ends without a blank line; unexpected unindent.
ERROR: InvocationError for command '/Users/wim/src/pytest/.tox/docs/bin/sphinx-build -W -b html . _build' (exited with code 2)

After much head scratching, I eventually figured the docstring is getting double-parsed. Python applies backslash processing to convert \n to a new line character in the docstring itself! So, in this line, there appears an invalid unindent after the \n. The solution is to escape the backslash (e.g. adding the r prefix on the docstring). I also changed it to be hopefully more consistent with the style of other docs.

Next roadblock: pytest's pre-commit hook was not working.

Return code: 3
Expected return code: 0
Output: 
    The path python3.6 (from --python=python3.6) does not exist

This one was easier to figure. The file .pre-commit-config.yaml hardcodes python3.6. I don't have python3.6 installed, only 2.7 and 3.7. However after changing it to python3.7, then there is:

[ERROR] Your pre-commit configuration is unstaged.
`git add .pre-commit-config.yaml` to fix this.

OK, I don't care, I committed the change with --no-verify, and then committed on a separate branch with the edited yaml to run the pre-commit hooks (this was not pushed and not in PR). One more thing that might have been nice: for the pre-commit to warn I hadn't included a file in changelog subdir - that was listed on the template text when creating a PR. I don't think the pre-commit should block on this, but perhaps just print a message about it - could be useful for first-time contributors?

[nicoddemus]

Thanks a lot @wimglenn, appreciate it!

One more thing that might have been nice: for the pre-commit to warn I hadn't included a file in changelog subdir - that was listed on the template text when creating a PR. I don't think the pre-commit should block on this, but perhaps just print a message about it - could be useful for first-time contributors?

That's a good idea, but I don't think pre-commit can handle that, because it works on commit basis, so it can't know if the branch will get a proper changelog entry later for example. Probably the best approach here is to have a towncrier bot of sorts instead.

cc @asottile

[asottile]

One more thing that might have been nice: for the pre-commit to warn I hadn't included a file in changelog subdir - that was listed on the template text when creating a PR. I don't think the pre-commit should block on this, but perhaps just print a message about it - could be useful for first-time contributors?

That's a good idea, but I don't think pre-commit can handle that, because it works on commit basis, so it can't know if the branch will get a proper changelog entry later for example. Probably the best approach here is to have a towncrier bot of sorts instead.

cc @asottile

I could imagine this being possible through a pre-push hook (which is supported by pre-commit! despite the name!) -- might be more annoying / harder to get right than it's worth though?

[nicoddemus]

might be more annoying / harder to get right than it's worth though?

Yeah, and users might always forget to install the pre-commit hook. We could also check that during linting, but it is also hard to get it right.

A bot really seems to be the proper solution, but AFAIK a "towncrier bot" doesn't exist (disclaimer: zero research done at this point 😆).