Improve Documentation

[jcjgraf]

Some points how the documentation could be improved:

• Settings overview

  • Indicate the domain of the setting options.
    • Some options may be more obvious (e.g. boolean settings) while others require analysing the source to figure out allowed values.
  • Indicate the default value.

• Document command line arguments

  • Briefly mention and describe all command line option. In addition a section with a few examples may be useful, especially after merging Vimiv as pipe #381

[karlch]

I agree that more documentation is always nice!

For both I would like to make sure that most of it stays fully automated, i.e. no need to manually update the documentation when we add another setting / command line flag. Additional examples and explanations are of course not part of this automation.

The question then is, how detailed we want to be. Would it be enough if we expand the settings table with two more columns, namely type (e.g. bool) and default (e.g. true)? We could possibly have a brief part before / after the table explaining any non-intuitive types, like the thumbnail size, without going into more details for every setting.

For the commandline arguments, is the information provided by vimiv --help enough except for the further examples?

[jcjgraf]

Keeping it simple by indicating the type including possible min/max values and default is sufficient I think. Using the handy scripts/src2rst.py and your nicely structured vimiv/api/settings.py it should doable I guess. If you do not mind I would look into this some time after #325 is done.

Concerning the CLI arguments. I think the information provided by the --help is enough if accompanied with a bunch of examples.