Hacker housekeeping

[ndim]

This does some housekeeping for hackers:

• make gitignore patterns more specific
• makes the source code formatting and code testing suggested by HACKING.md easily available by make and make check
• helps with writing *.md files by converting them to `*.html'
• goes through all errors reported by flake8 and starts fixing a number of them

Feel free to compla^Wcomment and cherrypick.

[lack]

A couple general points before I dive too far in:

• The flake8 settings should go in to the .flake8 config file instead of the makefile, so all invocations of flake8 have the same settings.
• I like the idea of a general cleanup/make-ready script, but I'm not a huge fan of it being a makefile... Too confusing because it doesn't actually build the software. Maybe a script in tools/? This way we could maybe set up githooks to auto-run these on commit...

[ndim]

As to the flake8 settings...

I presume the end goal is to have code which does not generate flake8 errors at all. At this time however, running flake8 produces pages of flake8 errors which is many more than can be fixed in an easy and clear commit.

To move from pages of errors to no errors at all it can be a helpful tactic to first ignore everything, and then turn on the errors one error class after the other. The fixes for each error class will be a few related changes which can be read and understood in a commit. Eventually, there will be no ignored errors left, and the code will be clean. Doing that by ignoring error classes outside of the .flake8 file separates the flake8 errors we actually want to ignore indefinitely (those are .flake8 material) from the errors we ignore just as a tactic to keep the number of errors to be fixed down to a manageable number to help in fixing the source.

I agree that errors which need to be ignored indefinitely should be ignored from .flake8, e.g. the dbus XML docstrings in case they are actually needed as they are for the DBUS code working properly, I have not found out yet whether that is the case). Some of my followup commits in this series regarding flake8 deal with flake8 errors which must be ignored in the longer term, so those I should probably move to the .flake8 file.

As to the choice of a makefile...

• make is very quick to type frequently while editing *.py files.

• A makefile is a very foreign concept for a proper Python package. I wanted to explicitly not interfere with the working of the actual Python package with this at all, so I thought it wasn't the worst of ideas to have a bit of help for developers to run in a four keystroke command make the several steps HACKING.md recommends to run, but clearly separated from the functionality of the actual Python package.

Anyway, if you think it is a better idea to have that functionality in Python, I can write that in Python. E.g. move the generation of *.html from *.md to setup.py build, and everything else into tools/cleanup-sources.py and tools/run-all-checks.py scripts. That is a lot more to type (and I presume the tools/cleanup-sources.py will be run quite often while working on any Python sources).

And BTW...

The .gitignore and HACKING.md related commits are unrelated to anything makefile related.

I have put an updated, cleaned up version of this pull request at https://github.com/lack/soundcraft-utils/pull/11 which contains nothing makefile related until very late in the patch series.

[ndim]

Superseded by https://github.com/lack/soundcraft-utils/pull/12.