Hello Jürgen, Am 16.09.2022 18:41 schrieb J. A.:
My goal is to ensure that each pushed commit contains only valid docstrings (and this includes valid markups and existing function names in references).
I see your point and I like it. ;) I know about code and docstring checkers (linters) that can be integrated in a unittest like pipeline. I use something like this for my own projects. As an example see here [1] a unittest and the related helper function invoking "pycodestyle" here [2]. This works well for me but I am not sure if it is a good solution because some professional developer told me once that this isn't a good idea. I can dive deeper into that topic and the different opinions about that when we want to implement a solution like this. But this wouldn't prevent errors with invalid references in docstrings because the linters don't follow the references. But Sphinx does of course.
It is, I have just tried this by adding invalid markups in a docstring
:py:func:`non_existing_function()` `config.Config()` missing namespace :func:`getConfig()`
The syntax of that docstring is valid but the content is not. So you want to validate the content of such strings.
and "make html" at least indicates problems with
reading sources... [100%] backintime
common/backintime.py:docstring of backintime.printAboutHeader:6: WARNING: Definition list ends without a blank line; unexpected unindent.
I am not sure if there are tools to handle that. Btw: that error is not about content but about syntax. I am still at the point that the html files generated from Sphinx don't belong in the repository. When generated every time we do a commit or PR... This would invoke an extra commit because the generated HTML files need to be commited. But I think Sphinx could be run and the output on stdout and stderr could be parsed by an extra script. And that script tell Travis OK or Error. Something like this. Never done this before. But the HTML files of that Spinx run should be thrown away. I would suggest that we should ask about that use case in the Sphinx and Travis community. Maybe there is an easier solution for this. One "big" problem we should have in mind is that in the current state the whole code and the docstrings are "ugly" and far away from any known convention. So when we start such checks for the whole code at once all lights go red and it will take months to clean all errors up. As you have seen I still do some code styling (PEP8) to some of the files. I do this step by step just in that part of code where I work and where I want to understand something. Currently IMHO it won't help us to check the whole repository with linters like pycodestale, flake8, pydocstyle, ... My IDE has an inbuild linter and the backintime files have round about 500 errors each. This is just the code not the docstrings. ;) And I am also not sure how foreign contributors would like that. For a "hobby programmer" or a first semester student it creates a lot of pressure when an PR needs to be 100% conform to PEP8 and other style guidelines. This also robs him of his sense of achievement. It gives you a good feeling when all lights are green after you invested time into a PR. ;) Kind Christian [1] -- <https://codeberg.org/buhtz/hyperorg/src/commit/463ca3607943f9d6651d08aa3f35a...> [2] -- <https://codeberg.org/buhtz/hyperorg/src/commit/463ca3607943f9d6651d08aa3f35a...>