Whilst working on the Reproducible Builds effort [0], we noticed
that sphinx could generate output that is not reproducible.
In particular, the rendering of `frozenset` objects in default
arguments and elsewhere is currently non-determinstic.
For example:
frozenset(['a', 'b', 'c'])
Might be rendered as any of:
frozenset({'a', 'b', 'c'})
frozenset({'a', 'c', 'b'})
frozenset({'b', 'a', 'c'})
frozenset({'b', 'c', 'a'})
frozenset({'c', 'a', 'b'})
frozenset({'c', 'b', 'a'})
Patch attached that sorts the contents of frozensets whilst rendering.
This is parallel to the `dict` and `set` type logic
[0] https://reproducible-builds.org/
As the previous commit explains, it is now possible to specify arguments
to the global options in config files. This means that we can now include
the `exclude-members` option in this global configuration.
Previously, there was no point including this option because it makes no
sense without arguments. Including this option means users have the
flexibility of explicitly including which special methods they want using
(e.g.):
:special-members: __init__, __iter__
or explicitly excluding which special-members (or other members) they want
using (e.g.):
:exclude-members: __weakref__, __hash__
Previously, users could specify a *list* of flags in their config files.
The flags were directive names that would otherwise be present in the
.rst files. However, as a list, it was not possible to specify values
to those flags, which *is* possible in .rst files.
For example, in .rst you could say
:special-members: __init__, __iter__
And this would cause autodoc to generate documents for these methods that
it would otherwise ignore.
This commit changes the config option to instead accept a dictionary.
This is a dictionary whose keys can contain the same flag-names as before,
but whose values can contain the arguments as seen in .rst files.
The old list is still supported, for backwards compatibility, but the data
is transformed into a dictionary when the user's config is loaded.
Setting mutable types as default arguments is bad practice because the
value is only initialised once. This means that defaults arguments of
lists and dictionaries which are modified during code execution *stay*
modified between calls.
In this case, the `options` dictionary accumulated options as more and
more test cases were executed. Without this change, the tests added in
the next commit do not pass.
See: https://stackoverflow.com/questions/1132941/least-astonishment-and-the-mutable-default-argument
