From: Serge Rehbinder Date: Tue, 2 Feb 2016 13:39:55 +0000 (+0100) Subject: format functions documentation for sphinx X-Git-Tag: sprint-02~20 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=50dc9b77554632f9b9e903e6fc17d5ecfd3dfc4a;p=tools%2Fsat.git format functions documentation for sphinx --- diff --git a/.gitignore b/.gitignore index ecc89eb..b9cceea 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ doc/build .coverage test/htmlcov test/test_res.html +doc/source/commands/apidoc diff --git a/src/common/__init__.py b/src/common/__init__.py index 170ed33..bad9eb5 100644 --- a/src/common/__init__.py +++ b/src/common/__init__.py @@ -31,6 +31,7 @@ class SatException(Exception): def ensure_path_exists(p): '''Create a path if not existing + :param p str: The path. ''' if not os.path.exists(p): @@ -38,6 +39,7 @@ def ensure_path_exists(p): def check_config_has_application( config, details = None ): '''check that the config has the key APPLICATION. Else raise an exception. + :param config class 'common.config_pyconf.Config': The config. ''' if 'APPLICATION' not in config: diff --git a/src/common/architecture.py b/src/common/architecture.py index 8a9b417..fe32ca8 100644 --- a/src/common/architecture.py +++ b/src/common/architecture.py @@ -23,13 +23,15 @@ In this file : all the stuff that can change with the architecture on which SAT import os, sys, platform, pwd def is_windows(): - '''method that checks windows OS + '''method that checks windows OS + :rtype: boolean ''' return platform.system() == 'Windows' def get_user(): '''method that gets the username that launched sat + :rtype: str ''' # In windows case, the USERNAME environment variable has to be set @@ -42,6 +44,7 @@ def get_user(): def _lsb_release(args): '''Get system information with lsb_release. + :param args str: The arguments to give to lsb_release. :return: The distribution. :rtype: str @@ -65,6 +68,7 @@ def _lsb_release(args): def get_distribution(codes): '''Gets the code for the distribution + :param codes L{Mapping}: The map containing distribution correlation table. :return: The distribution on which salomeTools is running, regarding the distribution correlation table contained in codes variable. :rtype: str @@ -86,6 +90,7 @@ def get_distribution(codes): def get_distrib_version(distrib, codes): '''Gets the version of the distribution + :param distrib str: The distribution on which the version will be found. :param codes L{Mapping}: The map containing distribution correlation table. :return: The version of the distribution on which salomeTools is running, regarding the distribution correlation table contained in codes variable. @@ -105,6 +110,7 @@ def get_distrib_version(distrib, codes): def get_nb_bit(): '''Gets the number of bytes. + :return: the number of bytes of the OS on which salomeTools is running. :rtype: str ''' @@ -123,6 +129,7 @@ def get_nb_bit(): def get_python_version(): '''Gets the version of the running python. + :return: the version of the running python. :rtype: str ''' @@ -132,6 +139,7 @@ def get_python_version(): def get_nb_proc(): '''Gets the number of processors of the machine on which salomeTools is running. + :return: the number of processors. :rtype: str ''' diff --git a/src/common/fileSystem.py b/src/common/fileSystem.py index 71c0046..cc8a39f 100644 --- a/src/common/fileSystem.py +++ b/src/common/fileSystem.py @@ -26,6 +26,7 @@ import subprocess def show_in_editor(editor, filePath): '''open filePath using editor. + :param editor str: The editor to use. :param filePath str: The path to the file to open. ''' diff --git a/src/common/options.py b/src/common/options.py index d597cf0..b54b190 100644 --- a/src/common/options.py +++ b/src/common/options.py @@ -35,6 +35,7 @@ class OptResult(object): def __getattr__(self, name): '''Overwrite of the __getattr__ function to customize it for option usage + :param name str: The attribute to get the value. :return: the value corresponding to the attribute. :rtype: str,int,list,boolean @@ -46,6 +47,7 @@ class OptResult(object): def __setattr__(self, name, value): '''Overwrite of the __setattr__ function to customize it for option usage + :param name str: The attribute to set. :param value str: The value corresponding to the attribute. :return: Nothing. @@ -66,6 +68,7 @@ class Options: def add_option(self, shortName, longName, optionType, destName, helpString=""): '''Method to add an option to a command. It gets all attributes of an option and append it in the options field + :param shortName str: The short name of the option (ex "l" for level option). :param longName str: The long name of the option (ex "level" for level option). :param optionType str: The type of the option (ex "int"). @@ -90,6 +93,7 @@ class Options: def print_help(self): '''Method that display all options stored in self.options and there help + :return: Nothing. :rtype: N\A ''' @@ -107,6 +111,7 @@ class Options: def parse_args(self, argList=None): '''Method that instantiates the class OptResult that gives access to all options in the code + :param argList list: the raw list of arguments that were passed :return: optResult, args : optResult is the option instance to manipulate in the code. args is the full raw list of passed options :rtype: (class 'common.options.OptResult',list) diff --git a/src/common/printcolors.py b/src/common/printcolors.py index 20f2d45..da76a47 100755 --- a/src/common/printcolors.py +++ b/src/common/printcolors.py @@ -43,6 +43,7 @@ __code_range__ = [1, 4] + list(range(30, 38)) + list(range(40, 48)) + list(range def printc(txt, code=''): '''print a text with colors + :param txt str: The text to be printed. :param code str: The color to use. :return: The colored text. @@ -66,6 +67,7 @@ def printc(txt, code=''): def printcInfo(txt): '''print a text info color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -74,6 +76,7 @@ def printcInfo(txt): def printcError(txt): '''print a text error color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -82,6 +85,7 @@ def printcError(txt): def printcWarning(txt): '''print a text warning color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -90,6 +94,7 @@ def printcWarning(txt): def printcHeader(txt): '''print a text header color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -98,6 +103,7 @@ def printcHeader(txt): def printcLabel(txt): '''print a text label color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -106,6 +112,7 @@ def printcLabel(txt): def printcSuccess(txt): '''print a text success color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -114,6 +121,7 @@ def printcSuccess(txt): def printcHighlight(txt): '''print a text highlight color + :param txt str: The text to be printed. :return: The colored text. :rtype: str @@ -122,6 +130,7 @@ def printcHighlight(txt): def cleancolor(message): '''remove color from a colored text. + :param message str: The text to be cleaned. :return: The cleaned text. :rtype: str @@ -133,6 +142,7 @@ def cleancolor(message): def print_value(logger, label, value, level=1, suffix=""): '''shortcut method to print a label and a value with the info color + :param logger class logger: the logger instance. :param label int: the label to print. :param value str: the value to print. @@ -146,6 +156,7 @@ def print_value(logger, label, value, level=1, suffix=""): def print_color_range(start, end): '''print possible range values for colors + :param start int: The smaller value. :param end int: The bigger value. ''' diff --git a/src/config.py b/src/config.py index 85e1579..9a9bec5 100644 --- a/src/config.py +++ b/src/config.py @@ -46,6 +46,7 @@ class ConfigOpener: ''' def __init__(self, pathList): '''Initialization + :param pathList list: The list of paths where to serach a pyconf. ''' self.pathList = pathList @@ -74,6 +75,7 @@ class ConfigManager: def _create_vars(self, application=None, command=None, dataDir=None): '''Create a dictionary that stores all information about machine, user, date, repositories, etc... + :param application str: The application for which salomeTools is called. :param command str: The command that is called. :param dataDir str: The repository that contain external data for salomeTools. @@ -142,7 +144,8 @@ class ConfigManager: def get_command_line_overrides(self, options, sections): '''get all the overwrites that are in the command line - :param options : the options from salomeTools class initialization (like -l5 or --overwrite) + + :param options: the options from salomeTools class initialization (like -l5 or --overwrite) :param sections str: The config section to overwrite. :return: The list of all the overwrites to apply. :rtype: list @@ -159,6 +162,7 @@ class ConfigManager: def getConfig(self, application=None, options=None, command=None, dataDir=None): '''get the config from all the configuration files. + :param application str: The application for which salomeTools is called. :param options calss Options: The general salomeToosl options (--overwrite or -l5, for example) :param command str: The command that is called. @@ -288,6 +292,7 @@ class ConfigManager: def setUserConfigFile(self, config): '''Set the user config file name and path. If necessary, build it from another one or create it from scratch. + :param config class 'common.config_pyconf.Config': The global config (containing all pyconf). ''' if not config: @@ -312,6 +317,7 @@ class ConfigManager: '''Get a pyconf file younger than the given sat version in the given directory The file basename can be one of salometools-.pyconf or salomeTools.pyconf Returns the file path or None if no file has been found. + :param userDir str: the directory that contain the user pyconf to find. (~/.salomeTools) :param sat_version str: the version of salomeTools. :return: the path to the already existing user pyconf. @@ -340,6 +346,7 @@ class ConfigManager: def createConfigFile(self, config): '''This method is called when there are no user config file. It build it from scratch. + :param config class 'common.config_pyconf.Config': The global config. :return: the config corresponding to the file created. :rtype: config class 'common.config_pyconf.Config' @@ -387,6 +394,7 @@ class ConfigManager: def print_value(config, path, show_label, level=0, show_full_path=False): '''Prints a value from the configuration. Prints recursively the values under the initial path. + :param config class 'common.config_pyconf.Config': The configuration from which the value is displayed. :param path str : the path in the configuration of the value to print. :param show_label boolean: if True, do a basic display. (useful for bash completion) @@ -432,6 +440,7 @@ def print_value(config, path, show_label, level=0, show_full_path=False): def description(): '''method that is called when salomeTools is called with --help option. + :return: The text to display for the config command description. :rtype: str ''' diff --git a/src/salomeTools.py b/src/salomeTools.py index 1ba2839..8fcf244 100755 --- a/src/salomeTools.py +++ b/src/salomeTools.py @@ -40,6 +40,7 @@ gettext.install('salomeTools', os.path.join(srcdir, 'common', 'i18n')) def find_command_list(dirPath): ''' Parse files in dirPath that end with .py : it gives commands list + :param dirPath str: The directory path where to search the commands :return: cmd_list : the list containing the commands name :rtype: list @@ -65,6 +66,7 @@ class salomeTools(object): ''' def __init__(self, opt, dataDir=None): '''Initialization + :param opt str: The sat options :param: dataDir str : the directory that contain all the external data (like software pyconf and software scripts) ''' @@ -94,6 +96,7 @@ class salomeTools(object): def __getattr__(self, name): ''' overwrite of __getattr__ function in order to display a customized message in case of a wrong call + :param name str: The name of the attribute ''' if name in self.__dict__: @@ -103,6 +106,7 @@ class salomeTools(object): def __setCommands__(self, dirPath): '''set class attributes corresponding to all commands that are in the dirPath directory + :param dirPath str: The directory path containing the commands ''' # loop on the commands name @@ -114,6 +118,7 @@ class salomeTools(object): def run_command(args): '''The function that will load the configuration (all pyconf) and return the function run of the command corresponding to module + :param args str: The directory path containing the commands ''' argv = args.split(" ") @@ -143,6 +148,7 @@ class salomeTools(object): def print_help(self, opt): '''Prints help for a command. Function called when "sat -h " + :param argv str: the options passed (to get the command name) ''' # if no command as argument (sat -h) @@ -176,6 +182,7 @@ class salomeTools(object): def get_module(self, module): '''Loads a command. Function called only by print_help + :param module str: the command to load ''' # Check if this command exists @@ -199,6 +206,7 @@ def print_version(): def print_help(): '''prints salomeTools general help + :param options str: the options ''' print_version() @@ -217,6 +225,7 @@ def print_help(): def write_exception(exc): '''write exception in case of error in a command + :param exc exception: the exception to print ''' sys.stderr.write("\n***** ")