From 44cba357e75aeb717f1b0f0360722703766a2b0e Mon Sep 17 00:00:00 2001 From: Christian Van Wambeke Date: Fri, 13 Apr 2018 15:44:24 +0200 Subject: [PATCH] add doc/README for make pdf info, je n'aime pas configuration tout court, what doe it mean? --- commands/clean.py | 71 ++++++++++++++++++++------------------ doc/README | 20 +++++++++++ doc/src/commands/clean.rst | 44 +++++++++++++++++++---- doc/src/index.rst | 18 ++++++---- 4 files changed, 107 insertions(+), 46 deletions(-) create mode 100644 doc/README diff --git a/commands/clean.py b/commands/clean.py index 805fa9a..b12182b 100644 --- a/commands/clean.py +++ b/commands/clean.py @@ -49,8 +49,9 @@ parser.add_option('', 'sources_without_dev', 'boolean', 'sources_without_dev', _("Optional: do not clean the products in development mode.")) def get_products_list(options, cfg, logger): - '''method that gives the product list with their informations from - configuration regarding the passed options. + """\ + method that gives the product list with their informations from + configuration regarding the passed options. :param options Options: The Options instance that stores the commands arguments @@ -58,7 +59,7 @@ def get_products_list(options, cfg, logger): :param logger Logger: The logger instance to use for the display and logging :return: The list of (product name, product_informations). :rtype: List - ''' + """ # Get the products to be prepared, regarding the options if options.products is None: # No options, get all products sources @@ -89,16 +90,17 @@ def get_products_list(options, cfg, logger): return products_infos def get_source_directories(products_infos, without_dev): - '''Returns the list of directory source paths corresponding to the list of - product information given as input. If without_dev (bool), then - the dev products are ignored. + """\ + Returns the list of directory source paths corresponding + to the list of product information given as input. + If without_dev (bool) the dev products are ignored. :param products_infos list: The list of (name, config) corresponding to one product. :param without_dev boolean: If True, then ignore the dev products. :return: the list of source paths. :rtype: list - ''' + """ l_dir_source = [] for __, product_info in products_infos: if product_has_dir(product_info, without_dev): @@ -106,14 +108,15 @@ def get_source_directories(products_infos, without_dev): return l_dir_source def get_build_directories(products_infos): - '''Returns the list of directory build paths corresponding to the list of - product information given as input. + """\ + Returns the list of directory build paths corresponding to the list of + product information given as input. :param products_infos list: The list of (name, config) corresponding to one product. :return: the list of build paths. :rtype: list - ''' + """ l_dir_build = [] for __, product_info in products_infos: if product_has_dir(product_info): @@ -122,14 +125,14 @@ def get_build_directories(products_infos): return l_dir_build def get_install_directories(products_infos): - '''Returns the list of directory install paths corresponding to the list of - product information given as input. + """\ + Returns the list of directory install paths corresponding to the list of + product information given as input. - :param products_infos list: The list of (name, config) corresponding to one - product. + :param products_infos list: The list of (name, config) corresponding to one product. :return: the list of install paths. :rtype: list - ''' + """ l_dir_install = [] for __, product_info in products_infos: if product_has_dir(product_info): @@ -137,14 +140,14 @@ def get_install_directories(products_infos): return l_dir_install def product_has_dir(product_info, without_dev=False): - '''Returns a boolean at True if there is a source, build and install - directory corresponding to the product described by product_info. + """\ + Returns a boolean at True if there is a source, build and install + directory corresponding to the product described by product_info. :param products_info Config: The config corresponding to the product. - :return: True if there is a source, build and install - directory corresponding to the product described by product_info. + :return: True if there is a source, build and install directory corresponding to the product described by product_info. :rtype: boolean - ''' + """ if (src.product.product_is_native(product_info) or src.product.product_is_fixed(product_info)): return False @@ -154,12 +157,11 @@ def product_has_dir(product_info, without_dev=False): return True def suppress_directories(l_paths, logger): - '''Suppress the paths given in the list in l_paths. + """Suppress the paths given in the list in l_paths. :param l_paths list: The list of Path to be suppressed - :param logger Logger: The logger instance to use for the display and - logging - ''' + :param logger Logger: The logger instance to use for the display and logging + """ for path in l_paths: if not path.isdir(): msg = _("Warning: the path %s does not " @@ -171,20 +173,23 @@ def suppress_directories(l_paths, logger): logger.write('%s\n' % src.printcolors.printc(src.OK_STATUS), 3) def description(): - '''method that is called when salomeTools is called with --help option. + """method called when salomeTools is called with --help option. :return: The text to display for the clean command description. :rtype: str - ''' - return _("The clean command suppress the source, build, or install " - "directories of the application products.\nUse the options to" - " define what directories you want to suppress and to reduce " - "the list of products\n\nexample:\nsat clean SALOME-master " - "--build --install --properties is_salome_module:yes") + """ + return _("""\ +The clean command suppress the SOURCES, BUILD or INSTALL directories of the application products. +Use the options to define what directories you want to suppress and to set the list of products + +example: +>> sat clean SALOME-xx --build --install --properties is_salome_module:yes +""") def run(args, runner, logger): - '''method that is called when salomeTools is called with clean parameter. - ''' + """\ + method called when salomeTools is called with clean parameter. + """ # Parse the options (options, args) = parser.parse_args(args) diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..f5ccaa7 --- /dev/null +++ b/doc/README @@ -0,0 +1,20 @@ + +# needs sphinx-build +# to make doc html + +cd doc +make html +firefox build/html/index.html & + +# to make doc pdf +# needs texlive a jour (done on machines lgls for x86_64-linux) +# https://www.tug.org/texlive/quickinstall.html + +export INFOPATH=/data/tmplgls/wambeke/share/texlive/2017/texmf-dist/doc/info +export MANPATH=/data/tmplgls/wambeke/share/texlive/2017/texmf-dist/doc/man +export PATH=/data/tmplgls/wambeke/share/texlive/2017/bin/x86_64-linux:${PATH} + +cd doc +make latexpdf +evince build/latex/salomeTools.pdf & + diff --git a/doc/src/commands/clean.rst b/doc/src/commands/clean.rst index f796d36..47935e6 100644 --- a/doc/src/commands/clean.rst +++ b/doc/src/commands/clean.rst @@ -6,19 +6,49 @@ Command clean Description ============ -The **clean** command -TODO -TODO + +The **clean** command removes products in the SOURCES, BUILD, or INSTALL directories of an application. + +Use the options to define what directories you want to suppress and to set the list of products Usage ======= -* Create a package for a product (example as *SALOME_xx*): :: - sat package SALOME_xx +* Clean all previously created *build* and *install* directories (example application as *SALOME_xx*): :: + + # take care, is long time to restore, sometimes + sat clean SALOME-xx --build --install - This command will create an archive named ``SALOME_xx.tgz`` in the working directory (``$USER.workDir``). - If the archive already exists an exception is thrown. +* Clean previously created *build* and *install* directories, only for products with property *is_salome_module*: :: + + sat clean SALOME-xxx --build --install \ + --properties is_salome_module:yes + + +Availables options +====================== + + * **--products**: Products to clean. + + * **--properties**: + + | Filter the products by their properties. + | Syntax: --properties : + + * **--sources**: Clean the product source directories. + + * **--build**: Clean the product build directories. + + * **--install**: Clean the product install directories. + + * **--all**: Clean the product source, build and install directories. + + * **--sources_without_dev**: + + | Do not clean the products in development mode. + | have they VCS_ commits pending? + Some useful configuration pathes diff --git a/doc/src/index.rst b/doc/src/index.rst index 799753b..69335c4 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -5,6 +5,10 @@ Salome Tools ************ +.. image:: images/sat_about.png + :scale: 100 % + :align: center + .. note:: This documentation is under construction. The **Sa**\ lome\ **T**\ ools (sat) is a suite of commands @@ -44,21 +48,23 @@ List of Commands package generate -Code documentation -================== +Developer documentation +======================= .. toctree:: :maxdepth: 1 - SAT modules + Add a command -Developer documentation -======================= + +Code documentation +================== .. toctree:: :maxdepth: 1 - Add a command + SAT modules + Release Notes ============= -- 2.39.2