Commands for Testing: Documentation

Documentation

Before moving on, let’s consider the documentation. ​​If any of the doc strings have been altered, it would be good to update the documentation.

pre-commit script

If we want, we can add the following lines in pre-commit to compile the documentation.

$ cd flask-examples/docs
$ make html
$ cd ..

This will compile the documentation, but it will not add the files to the commit. The pre-commit hook runs after git has determined what files to commit. Therefore, if we try to add files within pre-commit, we won’t affect the current commit, and would need to run commit again. However, committing from within the pre-commit script will fire off another copy of the pre-commit script and will likely descend into infinite recursion.

Approaches

So what are the options?

1. We could leave the docs out of the Git process altogether and depend on the developer(s) to run make html as needed.

2. Or, we could add the command to the script and have it update the files even though they won’t get pushed until the next commit, assuming they are being tracked and get added, but be careful to avoid infinite recursion.

3. We could attempt to determine if the documentation is up-to-date and then, if not, make them up-to-date and block the git commit. The developer will see what happened and rerun the same commit.

We follow the last approach by putting the following code in pre-commit