Automatically validate docstrings incl. Sphinx python domain directives and roles ("markup language")
During my development of https://github.com/bit-team/backintime/pull/1295 I had to modify a docstring and include references to other functions which can be done by via Sphinx roles, eg.: Args: cfg: A config created via :py:func:`config.Config()` or :py:func:`getConfig()` If would be great to validate these cross references automatically via TravisCI, a new make target or somehow else since generating the Sphinx doc and viewing the formatted doc manually is time consuming (and boring ;-) Could we add this to the TODO list + collect solution proposals?
Hello, I don't see what Travis has to do with this. There is no reference docu in the repository. And this is OK. Each developer need to run the Sphinx target on the local machine. Maybe Sphinx (or the "make html") should be more "--verbose" because I assume that Sphinx is able to validate such links by itself. I knew that feature from Doxygen and PyDoctor which both are able to give warnings and (if you want) errors about broken links. Kind Christian
My goal is to ensure that each pushed commit contains only valid docstrings (and this includes valid markups and existing function names in references). If only the developer was responsible for that it would be a decentral check with manual work. I'd like to see this "valid docstrings policy" to be enforced centrally so it cannot be forgotten. That is why TravisCI would be good possible tool to check also the docstrings (not only unit tests). Since I have never tried this with TravisCI am asking here...
Maybe Sphinx (or the "make html") should be more "--verbose" because I assume that Sphinx is able to validate such links by itself.
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()` 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. but the warning is not very intuitive (and only 1 out of 3 problems are discovered).
Hello Jürgen, Am 16.09.2022 18:41 schrieb J. A.:
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.
The syntax of that docstring is valid but the content is not. So you want to validate the content of such strings.
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...>
Hello, I don't see what Travis has to do with this. There is no reference docu in the repository. And this is OK. Each developer need to run the Sphinx target on the local machine. Maybe Sphinx (or the "make html") should be more "--verbose" because I assume that Sphinx is able to validate such links by itself. I knew that feature from Doxygen and PyDoctor which both are able to give warnings and (if you want) errors about broken links. Kind Christian
My goal is to ensure that each pushed commit contains only valid docstrings (and this includes valid markups and existing function names in references). If only the developer was responsible for that it would be a decentral check with manual work. I'd like to see this "valid docstrings policy" to be enforced centrally so it cannot be forgotten. That is why TravisCI would be good possible tool to check also the docstrings (not only unit tests). Since I have never tried this with TravisCI am asking here...
Maybe Sphinx (or the "make html") should be more "--verbose" because I assume that Sphinx is able to validate such links by itself.
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()` 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. but the warning is not very intuitive (and only 1 out of 3 problems are discovered).
Hello Jürgen, Am 16.09.2022 18:41 schrieb J. A.:
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.
The syntax of that docstring is valid but the content is not. So you want to validate the content of such strings.
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...>
participants (2)
-
c.buhtz＠posteo.jp -
J. A.