Document configuration options?
cboettig opened this issue · comments
It looks like an impressive number of configuration options can be set with a config.yml file, which seems like a great choice. I didn't find much discussion of config.yml. I think users might find it helpful if there was some documentation that described each of these options returned by sits_config_show(), with links to the appropriate sections of the documentation.
Similarly, it might be nice for the documentation or e-book to mention when these options are configurable. (For instance, the book's discussion of netrc makes no mention of the configuration for netrc file location).
Lastly, it's unclear how these options interact with other packages. For instance, it appears the configuration options duplicate some but not all of the configuration options that GDAL and gdalcubes provide. It would be good to document how a user is supposed to set some of these options, such as gdalcubes recommended settings for cloud access, https://gdalcubes.github.io/source/concepts/config.html#recommended-settings-for-cloud-access (perhaps these should even be set by default if they are not already)?)
Dear @cboettig, thanks for your useful suggestions.
We made a mistake in function sits_config_show(), which shows both parameters that are useful for user configuration (such as plot scales) and internal parameters used for checking function inputs. For example, the GDAL and gdalcubes options are internal defaults and should not be accessible to users. We will repair this function so that it shows only user-relevant parameters. In the upcoming version of the SITS book that describes version 1.5.1, we will expand the Technical Annex to provide a more detailed description of the most relevant configuration parameters.
Please note that we provide some information on sits internal organisation in the contributing.md, as required by rOpenSci guidelines. This information will be expanded and improved in the next edition of the sits book.
Many thanks for your support.
Dear @cboettig Many thanks for your useful suggestions. After careful deliberation, we decided to allow users to set some configuration parameters directly in the function call interface, specifically to control plotting and leaflet visualisation. The other configuration parameters will be not accessible to users. Most of our users are not programmers and they may setup wrong parameters by mistake.