[PATCH 1/1] Address comments

Gedare Bloom gedare at rtems.org
Thu Aug 2 13:13:03 UTC 2018


On Thu, Aug 2, 2018 at 12:55 AM, Dannie Huang <danxue.huang at gmail.com> wrote:
> ---
>  .gitignore               |  1 +
>  gen_rst_from_makedoc.py  | 71 ++++++----------------------------------
>  makedoc2rst_converter.py | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 96 insertions(+), 61 deletions(-)
>  create mode 100644 makedoc2rst_converter.py
>
> diff --git a/.gitignore b/.gitignore
> index 9f90354..f707fbd 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -1,2 +1,3 @@
>  .idea/*
>  __pycache__/*
> +*.rst
> diff --git a/gen_rst_from_makedoc.py b/gen_rst_from_makedoc.py
> index da69c80..4100756 100755
> --- a/gen_rst_from_makedoc.py
> +++ b/gen_rst_from_makedoc.py
> @@ -29,60 +29,8 @@
>  # POSSIBILITY OF SUCH DAMAGE.
>  #
>
> -
>  import argparse
> -import re
> -import rst
> -
> -
> -def is_command(s):
> -    """
> -    A command is a single word of at least 3 characters, all uppercase
> -    :param s: input string
> -    :return: True if s is a single command, otherwise False
> -    """
> -    return True if re.match('^[A-Z_]{3,}\s*$', s) else False
> -
> -
> -def extract_comments(content):
> -    """
> -    Extract content inside of /* */
> -    :param content: input file content
> -    :return: extracted comments
> -    """
> -    comments = ''
> -    comments_match = re.match('/\*(\*(?!/)|[^*])*\*/', content)
> -    if comments_match:
> -        wrapped_comments = comments_match.group()
> -        comments = wrapped_comments.lstrip('/*').rstrip('*/').lstrip().rstrip()
> -    return comments
> -
> -
> -def extract_command_and_text(content):
> -    """
> -    Extract command and text from input string content
> -    :param content: input string containing command and text
> -    :return: a tuple containing command and text
> -    """
> -    command = ''
> -    text = ''
> -    command_text_dict = {}
> -    for line in content.splitlines():
> -        if is_command(line):
> -            if command and text:
> -                command_text_dict[command] = text
> -            command = line.rstrip()
> -            text = ''
> -        else:
> -            text += line + '\n'
> -    return command_text_dict
> -
> -
> -def generate_rst(command_text_dict):
> -    rst_str = ''
> -    for command, text in command_text_dict.items():
> -        rst_str += rst.get_command_processor(command)(command, text)
> -    return rst_str
> +import makedoc2rst_converter
>
>
>  def get_parser():
> @@ -91,15 +39,15 @@ def get_parser():
>      )
>      parser.add_argument(
>          '-s',
> -        '--source_file_dir',
> +        '--source_file_path',
>          type=str,
> -        help='Source file directory with newlib style comments',
> +        help='Path of source file with newlib style comments',
>      )
>      parser.add_argument(
>          '-d',
> -        '--dest_file_dir',
> +        '--dest_file_path',
>          type=str,
> -        help='Destination directory for converted rst markup file',
> +        help='Path of destination file with rst markup',
>      )
>      return parser
>
> @@ -108,18 +56,19 @@ def main(source_file_dir, dest_file_dir):
>      with open(source_file_dir, 'r') as source_file, open(dest_file_dir, 'w') as dest_file:
>          file_content = source_file.read()
>
> +        makedoc2rst = makedoc2rst_converter.makedoc2rst_converter()
>          # Get comments inside of /* */
> -        comments = extract_comments(file_content)
> +        comments = makedoc2rst.extract_comments(file_content)
>
>          # Parse comments
> -        command_text_dict = extract_command_and_text(comments)
> +        command_text_dict = makedoc2rst.extract_command_and_text(comments)
>
>          # Process text based on command type
> -        rst_str = generate_rst(command_text_dict)
> +        rst_str = makedoc2rst.generate_rst(command_text_dict)
>
>          dest_file.write(rst_str)
>
>
>  if __name__ == '__main__':
>      args = get_parser().parse_args()
> -    main(args.source_file_dir, args.dest_file_dir)
> +    main(args.source_file_path, args.dest_file_path)
> diff --git a/makedoc2rst_converter.py b/makedoc2rst_converter.py
> new file mode 100644
> index 0000000..e4d2d72
> --- /dev/null
> +++ b/makedoc2rst_converter.py
> @@ -0,0 +1,85 @@
> +#!/usr/bin/env python
> +#
> +# RTEMS Tools Project (http://www.rtems.org/)
> +# Copyright 2018 Danxue Huang (danxue.huang at gmail.com)
> +# All rights reserved.
> +#
> +# This file is part of the RTEMS Tools package in 'rtems-tools'.
> +#
> +# Redistribution and use in source and binary forms, with or without
> +# modification, are permitted provided that the following conditions are met:
> +#
> +# 1. Redistributions of source code must retain the above copyright notice,
> +# this list of conditions and the following disclaimer.
> +#
> +# 2. Redistributions in binary form must reproduce the above copyright notice,
> +# this list of conditions and the following disclaimer in the documentation
> +# and/or other materials provided with the distribution.
> +#
> +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
> +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
> +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
> +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
> +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
> +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
> +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
> +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
> +# POSSIBILITY OF SUCH DAMAGE.
> +#
> +
> +import re
> +import rst
> +
> +
> +class makedoc2rst_converter():

Pydoc for the class?

I think makedoc2rst() would be a suitable name for the class.

I would like to see a constructor that takes an input file name to
process, and the class should handle all the file open / read
semantics internally, throwing the same exceptions if any.

I think a reasonable interface for this kind of class is something like...

makedoc2rst::convert( cfile, rstfile )

Then  you can also define some constructor like
makedoc2rst( cfile, rstfile ):
  return self.convert(cfile, rstfile)

I don't see any reason to have any more complicated interface than this.

> +    @staticmethod
I don't see a need for these to be staticmethods.

You could make them private methods.

> +    def is_command(s):
> +        """
> +        A command is a single word of at least 3 characters, all uppercase
> +        :param s: input string
> +        :return: True if s is a single command, otherwise False
> +        """
> +        return True if re.match('^[A-Z_]{3,}\s*$', s) else False
> +
> +    @staticmethod
> +    def extract_comments(content):
> +        """
> +        Extract content inside of /* */
> +        :param content: input file content
> +        :return: extracted comments
> +        """
> +        comments = ''
> +        comments_match = re.match('/\*(\*(?!/)|[^*])*\*/', content)
> +        if comments_match:
> +            wrapped_comments = comments_match.group()
> +            comments = wrapped_comments.lstrip('/*').rstrip('*/').lstrip().rstrip()
> +        return comments
> +
> +    @staticmethod
> +    def extract_command_and_text(content):
> +        """
> +        Extract command and text from input string content
> +        :param content: input string containing command and text
> +        :return: a tuple containing command and text
> +        """
> +        command = ''
> +        text = ''
> +        command_text_dict = {}
> +        for line in content.splitlines():
> +            if makedoc2rst_converter.is_command(line):
> +                if command and text:
> +                    command_text_dict[command] = text
> +                command = line.rstrip()
> +                text = ''
> +            else:
> +                text += line + '\n'
> +        return command_text_dict
> +
> +    @staticmethod
> +    def generate_rst(command_text_dict):
> +        rst_str = ''
> +        for command, text in command_text_dict.items():
> +            rst_str += rst.get_command_processor(command)(command, text)
> +        return rst_str
> --
> 2.7.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel



More information about the devel mailing list