Skip to content

Create pre-commit hook #202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eldipa merged 2 commits into from
Nov 1, 2021
Merged

Create pre-commit hook #202

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a7e899
Create .pre-commit-hooks.yaml
jeertmans Oct 24, 2021
9c1c903
Update .pre-commit-hooks.yaml
jeertmans Oct 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .pre-commit-hooks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
- id: byexample
name: run code snippets in docstrings to validate them

@eldipa eldipa Oct 31, 2021

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@jeertmans jeertmans Nov 1, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

description: avoids writing errorneous code snippets.

@eldipa eldipa Oct 31, 2021

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jeertmans jeertmans Nov 1, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

entry: byexample
language: python
require_serial: true