Conversation
|
Nice!, I'm not familiar with |
|
Just to mention that if you are interested in pre-commit, I suggest you to also create (or I can do it for your) a config file for this repository such that future commits can use the pre-commit hook to avoid common programming mistakes or allow for a more unified syntax (using black linting for example). Then, you can also setup automatic github actions or use the free pre-commit.ci service that will automatically run your pre-commit hook on Pull Requests (or more). If you want more information about how it works, or on how to integrate it to your project, feel free to ask :) |
eldipa
left a comment
There was a problem hiding this comment.
Thanks a lot for suggesting pre-commit. Indeed seems to be an useful idea to integrate it with byexample.
I added a few rephrasesing. I'm okay with merging it as is and making the changes myself later but I wanted to show them to you for comments. (or if you want to do the changes, I'm okay too).
Let me know what you think.
| @@ -0,0 +1,6 @@ | |||
| - id: byexample | |||
| name: run code snippets in docstrings to validate them | |||
There was a problem hiding this comment.
We could rephrase this as "Run code snippets to validate them". I'm not 100% sure of my own proposal but I think that the word "docstring" suggests that it will only work for Python's docstrings which it's only one option.
What do you think?
There was a problem hiding this comment.
Indeed, you are correct. I am most familiar with Python’s docstrings and I did not think of the fact that not all languages put their docs into strings or use this term :)
| @@ -0,0 +1,6 @@ | |||
| - id: byexample | |||
| name: run code snippets in docstrings to validate them | |||
| description: avoids writing errorneous code snippets. | |||
There was a problem hiding this comment.
While it is correct that a failing example may mean an error in the code snippet, it is only one side of the coin. A failing example may mean that the snippet is correct but the source code that you are documenting is not.
Perhaps a better description could be:
byexample a literate programming engine where you mix ordinary text and snippets of code in the same file and then you execute them as regression tests.
You can always be sure that the examples are correct and your documentation is up to date!
I couldn't find where this information is shown or used by pre-commit but I guess that a multiline description like above should be supported.
There was a problem hiding this comment.
Well I did not find much information about this neither. I mostly got inspiration from pre-commit’s pre-commit-hooks.
However, I don’t think the description matters much as it won’t be read by many people: in my opinion, people that use per-commit hooks already know what the hooks are doing or should get more information elsewhere than in that very file.
|
@jeertmans merged! The feature is available from version Thanks a lot for the contribution! |
|
You are welcome, and thanks for your involvement in my PR! byexample is a great project and I am thankful it exists ;) |
Hello,
I recently forked your repo to add a pre-commit hook to it, and use that for another project (see here).
In short, one can use byexample in his
.pre-commit-config.yamlfile:As I think it may interest many people, I propose this pull-request.
Feel free to ask me for any change, or tell me if you dislike my proposition.