Add numpydoc section name checker

[akaszynski]

Simple PR to add a section name checker.

This won't auto-format, but instead will outright fail. In our documentation builder in pyvista, it would be helpful to have this fail on pre-commit rather during the documentation build.

Also adds in a section to raise an error and indicate which file and docstring caused the error. This made it much easier to debug invalid documentation strings from our documentation.

[DanielNoord]

Could you add a test for this? That helps reviewing what you want the desired behaviour to be!

[DanielNoord]

Please remove this from the .gitignore

[akaszynski]

I'm fine with doing that, but this means there will be a ton of *.pyc files that have to be ignored. For example:

Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        pydocstringformatter/__pycache__/
        pydocstringformatter/_configuration/__pycache__/
        pydocstringformatter/_formatting/__pycache__/
        pydocstringformatter/_utils/__pycache__/

no changes added to commit (use "git add" and/or "git commit -a")

We might also consider ignoring __pycache__ as in:

https://github.com/pandas-dev/pandas/blob/fb754d71db2897b40dd603e880a15e028f64f750/.gitignore#L72

[DanielNoord]

Are you opposed to ignoring __pycache__ in ~/.gitignore? In general I don't ever see the need to commit those files to git.

[akaszynski]

Are you opposed to ignoring __pycache__ in ~/.gitignore? In general I don't ever see the need to commit those files to git.

I never considered adding in a a global git ignore, and it seems that others do it as well (as in this SO answer). However, I can't assume that every user will have these files ignored.

Either way, I'll respect your wishes.

[github-actions]

According to the primer, this change has no effect on the checked open source code. 🤖🎉

[akaszynski]

This is failing due to the additional argument:

https://github.com/akaszynski/pydocstringformatter/blob/ce16320c603d2cb5cff20f029fd26d6a75fe4d91/tests/test_run.py#L159-L167

I can't reason why this file name needs to include the names of all the arguments.

---

The other failure is because I'm now raising an error and not continuing the autoformatter. If you would prefer to writing to stderr instead, let me know. Otherwise, we'll need a different way of dealing with this in the test (perhaps a try/except). However, I would prefer to follow the "pattern".

[DanielNoord]

This is failing due to the additional argument:

https://github.com/akaszynski/pydocstringformatter/blob/ce16320c603d2cb5cff20f029fd26d6a75fe4d91/tests/test_run.py#L159-L167

I can't reason why this file name needs to include the names of all the arguments.

Yeah, this makes no sense. Would you mind changing this? Perhaps by adding a UUID or global counter to make sure file names don't clash.

The other failure is because I'm now raising an error and not continuing the autoformatter. If you would prefer to writing to stderr instead, let me know. Otherwise, we'll need a different way of dealing with this in the test (perhaps a try/except). However, I would prefer to follow the "pattern".

I think writing to stderr would be better? Combined with setting an exit code? Would that fix your original issue?

Sorry for taking so long to respond. Life got busy suddenly!

[DanielNoord]

Follow up in #278