From df036fbe95b36a51ef6749811eff4e966416399d Mon Sep 17 00:00:00 2001 From: Christian Herdtweck Date: Tue, 17 May 2022 14:43:11 +0200 Subject: [PATCH] Fix errors in api doc creation There were a number of warnings and errors when creating docs, resulting in html docs that were screwed up in a few places. Fixed those. --- src/argparse_helpers.py | 10 ++++++---- src/arnied_wrapper.py | 2 +- src/cnfvar/string.py | 12 ++++++------ src/log_helpers.py | 14 +++++++------- src/log_read.py | 10 ++++++---- src/mail_utils.py | 10 +++++----- src/sysmisc.py | 2 +- 7 files changed, 32 insertions(+), 28 deletions(-) diff --git a/src/argparse_helpers.py b/src/argparse_helpers.py index 93e4bad..a8d0d04 100644 --- a/src/argparse_helpers.py +++ b/src/argparse_helpers.py @@ -19,10 +19,12 @@ """ argparse_helpers: Some convenience helpers for argparse -Featuring -- NonExitingParser: a subclass of ArgumentParser that does not do sys.exit(2) - on parse error but instead raises a ArgParserWantsExit exception. -- function existing_file which can be used as a type in add_argument() calls +Featuring: + - NonExitingParser: a subclass of :py:class:`argparse.ArgumentParser` + that does not do *sys.exit(2)* on parse error but instead raises a + :py:class:`ArgParserWantsExit` exception. + - function existing_file/dir[_or_empty] which can be used as a type in calls to + :py:func:`argparse.ArgumentParser.add_argument` .. codeauthor:: Intra2net """ diff --git a/src/arnied_wrapper.py b/src/arnied_wrapper.py index 8101dd5..102a330 100644 --- a/src/arnied_wrapper.py +++ b/src/arnied_wrapper.py @@ -347,7 +347,7 @@ def wait_for_generate(timeout=300, vm=None): """ Wait for the 'generate' program to complete. - Arguments are similar to the ones from :py:method:`wait_for_run`. + Arguments are similar to the ones from :py:func:`wait_for_run`. """ wait_for_run('generate', timeout=timeout, retries=1, vm=vm) wait_for_run('generate_offline', timeout=timeout, retries=1, vm=vm) diff --git a/src/cnfvar/string.py b/src/cnfvar/string.py index 0aec596..773f8a2 100644 --- a/src/cnfvar/string.py +++ b/src/cnfvar/string.py @@ -677,12 +677,12 @@ def cnf_root(root): :rtype: [dict] Output varies depending on a few conditions: - - If `root` is a list, return it right away - - If `root` is a dict corresponding to a valid CNF value, return it wrapped - in a list - - If `root` is a dict with a `cnf` key containg a list (as the JSON - returned by `get_cnf -j`), return the value - - Otherwise, raise an error + - If `root` is a list, return it right away + - If `root` is a dict corresponding to a valid CNF value, return it wrapped + in a list + - If `root` is a dict with a `cnf` key containg a list (as the JSON + returned by `get_cnf -j`), return the value + - Otherwise, raise an error """ if isinstance(root, list): return root diff --git a/src/log_helpers.py b/src/log_helpers.py index 87ab5f2..9f12bc6 100644 --- a/src/log_helpers.py +++ b/src/log_helpers.py @@ -28,12 +28,12 @@ I2nLogger: logger that provides a notice(), allows omission for str.format get_logger: factor for creating I2nLoggers -Further ideas: :: -* allow milliseconds in dateformat field (see test_short_level_format) -* create own basicConfig-like function that uses our classes as default - --> started using I2nLogger constructor and get_logger -* try to find out module that calls I2nLogger constructor to provide a good - default value for name (finding out the current module is a pain in the a..) +Further ideas: + * allow milliseconds in dateformat field (see test_short_level_format) + * create own basicConfig-like function that uses our classes as default + --> started using I2nLogger constructor and get_logger + * try to find out module that calls I2nLogger constructor to provide a good + default value for name (finding out the current module is a pain in the a..) .. todo:: create unittests from test_* functions at bottom .. todo:: think about how to allow different levels per handler @@ -180,7 +180,7 @@ class I2nLogger: * can limit the number of lines this logger will produce to prevent filling hard drive with log file (assumes one line per call to log/debug/info/notice/..., - only counts calls with priority above this logger's level) + only counts calls with priority above this logger's level) * provides shorter method names: dbg, note, warn, err * adds a NullHandler if `streams` and `files` and `handlers` are all `None` * convenience functions to add most frequently used handlers diff --git a/src/log_read.py b/src/log_read.py index 724f4e1..4eba2a4 100644 --- a/src/log_read.py +++ b/src/log_read.py @@ -292,7 +292,7 @@ class IterativeReader(object): Intended for overwriting in subclasses. - This function is called from __iter__ for each new data that becomes + This function is called from `__iter__` for each new data that becomes available. It has to provide results which are forwarded to caller. This base implementation just yields its input, so new data is yielded @@ -302,7 +302,7 @@ class IterativeReader(object): :py:data:`self.descriptions` :param str data: Text data read from source :param idx: Index of data source - :returns: nothing but yields [(description, data, idx], same as input + :returns: nothing but yields [(description, data, idx)], same as input """ yield description, data, idx @@ -330,6 +330,7 @@ class LineReader(IterativeReader): If line is not complete, then buffer it. Args: see super class method :py:meth:`IterativeReader.prepare_result` + :returns: list of 3-tuples `(description, line, idx)` where `description` and `idx` are same as args, and `line` is without trailing newline characters @@ -358,7 +359,7 @@ class LogParser(LineReader): Iteration returns :py:class:`re.match` result or -- if matching failed -- None. The latest unparsed line is available as `self.last_unparsed_line`. - Usage recommendation: + Usage recommendation:: with open(log_file_name, 'rt') as file_handle: parser = log_read.LogParser(file_handle, pattern=my_pattern): @@ -389,6 +390,7 @@ class LogParser(LineReader): Try parsing lines. Args: see super class method :py:meth:`IterativeReader.prepare_result` + :returns: 3-tuples `(description, line, idx)` where `description` and `idx` are same as input args and `line` is either a :py:class:`re.Match` if line matched :py:data:`self.pattern` @@ -411,7 +413,7 @@ class LogParser(LineReader): """ Open single file, yield LogParser. Ensures file is closed afterwards. - This allows opening file and creation LogParser for it to one line: + This allows opening file and creation LogParser for it to one line:: with LogParser.create_for('/var/log/messages', SYS_LOG_PATTERN) as parser: for _, matches, _ in parser: diff --git a/src/mail_utils.py b/src/mail_utils.py index 64759a4..42c1d2e 100644 --- a/src/mail_utils.py +++ b/src/mail_utils.py @@ -92,7 +92,7 @@ def parse_mail_file(file_name, headers_only=True, attachment_filenames=False, Removes the SMTP envelope surrounding the email if present. Only left-over might be a line with a '.' at end of non-multipart messages if - `headers_only` is False. + `headers_only` is False. :param str file_name: path to the file that contains the email text :param bool headers_only: whether to parse only the email headers; set this @@ -238,17 +238,17 @@ def get_message_text(filename, fallback_encoding='iso8859-1', continue ... - Finds the first part in message that is of type text/plain and decodes it + Finds the first part in message that is of type `text/plain` and decodes it using encoding specified in mail or otherwise fallback encoding. If none - found takes first part of type "text/*", or otherwise just the first part. + found takes first part of type `text/*`, or otherwise just the first part. - If include_all_text is True, all text/* parts are included, with text/plain + If include_all_text is True, all `text/*` parts are included, with `text/plain` being the first. :param str filename: complete path of message file in filesystem :param str fallback_encoding: Encoding of email text if none is specified in mail. - :param bool include_all_text: include all "text/*" parts in returned text + :param bool include_all_text: include all `text/*` parts in returned text :returns: text(s) of message :rtype: [str] if include_all_text else str """ diff --git a/src/sysmisc.py b/src/sysmisc.py index 8f9e8df..4bea76d 100644 --- a/src/sysmisc.py +++ b/src/sysmisc.py @@ -342,7 +342,7 @@ def cmd_block_till(cmd, timeout, cond, interval=1, *userdata, **kwuserdata): :param cond: Function to call; code will wait for this to return something other than `False` :param interval: Time (in seconds) to sleep between each attempt at `cond` - :returns: Pair of result and error message if appropriate or :py:value:`None`. + :returns: A Pair of result and error message if appropriate or `None`. :rtype: (run_result, str | None) """ llog.debug("cmd_block_till: %r, %d s, %r", cmd, timeout, cond) -- 1.7.1