there is chance that the default value of an option is empty, before
this change the rendered result would be "````", and sphinx is confused
at seeing this:
Unexpected section title or transition.
as it takes it as a notion of section title. after this change,
the "literal" filter is always applied to the default value, so an empty
string is rendered like "<empty string>" instead.
Signed-off-by: Kefu Chai <kchai@redhat.com>
less repeating this way, this change also addresses the missing option
issue if the option to be rendered is the first option in a document,
and there is no "mgr_module" directive before it.
Signed-off-by: Kefu Chai <kchai@redhat.com>
before this change,
.. mgr_module:: None
is required at end of a mgr module document to reset the context, so
the builder env is not polluted when processing the next document.
after this change, this ending directive is not needed anymore.
Signed-off-by: Kefu Chai <kchai@redhat.com>
instead of collecting all options from all modules, just load the
options from the specified module, this addresses the issue where
options with the same name are overriden by the options defined by
another mgr module.
Signed-off-by: Kefu Chai <kchai@redhat.com>
in addition to "mgr_module" directive, add the "module" option to
confval. this allows a certain option to specify its own module without
being nested in a "mgr_module" directive pair.
Signed-off-by: Kefu Chai <kchai@redhat.com>
which allows us to use different scheme when defining an option,
without this change, if two options in different mgr module share the
same name we cannot differentiate them, after this change, their id
would prefixed with the module name.
Signed-off-by: Kefu Chai <kchai@redhat.com>
there is chance that we don't have desc, desc_long or fmt_desc, in that
case, we should just skip desc before checking its length. so, just use
'if desc' which is able to check for None or empty string.
Signed-off-by: Kefu Chai <kchai@redhat.com>
default could be None and we don't reference the default value using
`opt.default`, so this variable is always defined. to avoid printing
a None default value, check for a None value. see
https://jinja.palletsprojects.com/en/2.11.x/templates/#none
Signed-off-by: Kefu Chai <kchai@redhat.com>
before this change, the rendered Default is "0Ei" if the default size is 0,
would be more readable if it is "0B" or "0".
Signed-off-by: Kefu Chai <kchai@redhat.com>
before this change, we check the exisitence of default value of an
option using "if default", but this is wrong. what if "default" is an
empty string or a numeric value of 0, or just False?
after this change, its exisitence is checked using "if default is
defined", so all "false" default values are rendered as well.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to format size options in the same format supported by our C++
strict_iec_cast() parser. so they are more consistent from user's
perspective.
Signed-off-by: Kefu Chai <kchai@redhat.com>
* add a field named "fmt_desc", which is the description formatted using
reStructuredText. it is preserved as it is if it's different from the
desc or long_desc of an option. we can consolidate it with long_desc
in future, and use pretty printer which has minimal support for
reStructuredText for printing the formatted descriptions for a better
user experience of command line. but at this moment, fmt_desc has
only one consumer: the "ceph_confval" sphinx extension which extracts
and translate the options yaml file to reStructuredText, which is in
turn rendered by sphinx.
* remove unused options from the doc
- journal_queue_max_ops
- journal_queue_max_bytes
Signed-off-by: Kefu Chai <kchai@redhat.com>
