From b371676debccaa2abf20bb4b0a4fdce34647987b Mon Sep 17 00:00:00 2001 From: Christian Van Wambeke Date: Thu, 12 Apr 2018 16:27:38 +0200 Subject: [PATCH] fix package.rst etc --- commands/package.py | 2 +- doc/rst_prolog.rst | 3 ++ doc/src/commands/application.rst | 5 +- doc/src/commands/clean.rst | 89 ++------------------------------ doc/src/commands/compile.rst | 9 ++-- doc/src/commands/config.rst | 64 ++++++++++++++++------- doc/src/commands/environ.rst | 5 +- doc/src/commands/launcher.rst | 6 ++- doc/src/commands/log.rst | 5 +- doc/src/commands/package.rst | 64 +++++++---------------- doc/src/commands/prepare.rst | 5 +- doc/src/conf.py | 2 +- 12 files changed, 94 insertions(+), 165 deletions(-) diff --git a/commands/package.py b/commands/package.py index e1126e0..6d39d9b 100644 --- a/commands/package.py +++ b/commands/package.py @@ -1158,7 +1158,7 @@ def description(): :rtype: str ''' return _(""" -The package command creates an tar archive of a product. +The package command creates a tar file archive of a product. There are four kinds of archive, which can be mixed: 1 - The binary archive. diff --git a/doc/rst_prolog.rst b/doc/rst_prolog.rst index 9ead7c9..eb91315 100644 --- a/doc/rst_prolog.rst +++ b/doc/rst_prolog.rst @@ -15,4 +15,7 @@ .. _CLI: https://en.wikipedia.org/wiki/Command-line_interface .. _Tar: https://en.wikipedia.org/wiki/Tar_(computing) .. _OS: https://en.wikipedia.org/wiki/Operating_system +.. _VCS: https://en.wikipedia.org/wiki/Version_control +.. _CVS: https://fr.wikipedia.org/wiki/Concurrent_versions_system +.. _SVN: https://en.wikipedia.org/wiki/Apache_Subversion diff --git a/doc/src/commands/application.rst b/doc/src/commands/application.rst index 908e935..f753b39 100644 --- a/doc/src/commands/application.rst +++ b/doc/src/commands/application.rst @@ -38,8 +38,9 @@ Usage This will create a catalog by querying each machine through ssh protocol (memory, number of processor) with ssh. -Configuration -============= +Some useful configuration pathes +================================= + The virtual application can be configured with the virtual_app section of the configutation file. * APPLICATION.virtual_app diff --git a/doc/src/commands/clean.rst b/doc/src/commands/clean.rst index 33a0a7c..f796d36 100644 --- a/doc/src/commands/clean.rst +++ b/doc/src/commands/clean.rst @@ -9,20 +9,10 @@ Description The **clean** command TODO TODO -. -Depending on the selected options, the created archive includes sources and binaries -of SALOME products and prerequisites. - -Utility *salomeTools* is also included in the archive. - -.. important:: - By default the package only includes the sources of the prerequisites and the products. - To select a subset use the *--content* option. - Usage -===== +======= * Create a package for a product (example as *SALOME_xx*): :: sat package SALOME_xx @@ -30,81 +20,8 @@ Usage 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. -* Create a package with a specific name: :: - - sat package SALOME_xx --name YourSpecificName - -.. important:: - By default, the archive is created in the working directory of the user (``$USER.workDir``). - If the option *name* is used with a path (relative or absolute) it will be used. - If the option *name* is not used and binaries (modules or prerequisites) are - included in the package, the architecture (ex: MD10_64) will be appened to the name. - - Example: :: - - sat package - Creates .tar.gz in $USER.workDir - - sat package -b - Creates _.tar.gz in $USER.workDir - - sat package -n myname - Creates myname.tar.gz in $USER.workDir - - sat package -n ~/myname -b - Creates myname.tar.gz in the home directory - -* Force the creation of the archive (if it already exists): :: - - sat package --force - -* Include the binaries in the archive (modules and prerequisites): :: - - sat package --binaries - - This command will create an archive named ``_.tar.gz`` where is the architecture of the machine. - -* Set content of the archive: :: - - # only the prerequisites - sat package --content ps,pb - # only the modules sources - sat package --content ms - # only the binaries - sat package --content mb,pb - - - Possible values for content option are: - * ms: modules sources - * mb: modules binaries - * ps: prerequisites sources - * pb: prerequisites binaries - - .. note:: this option is not compatible with the *--binaries* option. - -* Include the modules and prerequisites of the base product: :: - - sat package --with_base - -* Simulate the creation of the package (only check for required components): :: - - sat package --simulate - -* Do not include sample modules (like HELLO): :: - - sat package --no_sample - - Sample modules are identified by the ``$TOOLS.common.module_info..module_type`` parameter. - - By default salomeTools creates a copy of the installer with the same name than - the package. Use this option to not generate the installer. - -* Do not delete version control system informations from the configurations files of the embedded salomeTools: :: - - sat package --with_vcs - The version control systems (vcs) taken into account by this option are CVS, SVN and Git. +Some useful configuration pathes +================================= -Configuration -============= No specific configuration. diff --git a/doc/src/commands/compile.rst b/doc/src/commands/compile.rst index 8d057fd..c7cd044 100644 --- a/doc/src/commands/compile.rst +++ b/doc/src/commands/compile.rst @@ -32,7 +32,9 @@ Usage * Clean the build and install directories before starting compilation: :: sat compile --products GEOM --clean_all - Note: a warning will be shown if option --products is missing (as it will clean everything!) + + .. note:: | a warning will be shown if option --products is missing + | (as it will clean everything) * Clean only the install directories before starting compilation: :: @@ -59,8 +61,9 @@ Usage sat compile --show -Configuration -============= +Some useful configuration pathes +================================= + The way to compile a product is defined in the product configuration file (pyconf). The main options are: diff --git a/doc/src/commands/config.rst b/doc/src/commands/config.rst index d8ee61f..3e1a743 100644 --- a/doc/src/commands/config.rst +++ b/doc/src/commands/config.rst @@ -4,7 +4,8 @@ Command config Description =========== -The **config** command manages sat configuration. It allows display, manipulation and operation on configuration files +The **config** command manages sat configuration. +It allows display, manipulation and operation on configuration files Usage ===== @@ -24,35 +25,60 @@ Usage sat config --copy [new_name] -* Print the value of a configuration parameter. Use the automatic completion to get recursively the parameter names. Use -n option to get only the value, not the lable (useful in automatic scripts). Examples: :: +* | Print the value of a configuration parameter. + | Use the automatic completion to get recursively the parameter names. + | Use *--no_label* option to get *only* the value, *without* label (useful in automatic scripts). + | Examples (with *SALOME-xx* as *SALOME-8.4.0* ): - sat config --value + :: + + # sat config --value + sat config --value . # all the configuration sat config --value LOCAL sat config --value LOCAL.workdir - sat config --value - sat config SALOME-8.4.0 --value APPLICATION.workdir - sat config SALOME-8.4.0 -n --value APPLICATION.workdir + # sat config --value + sat config SALOME-xx --value APPLICATION.workdir + sat config SALOME-xx --no_label --value APPLICATION.workdir + +* | Print in one-line-by-value mode the value of a configuration parameter, + | with its source *expression*, if any. + | This is a debug mode, useful for developers. + | Prints the parameter path, the source expression if any, and the final value: + + :: + + sat config SALOME-xx -g USER + + .. note:: And so, not only for fun, to get **all expressions** of configuration + :: + + sat config SALOME-xx -g . | grep -e "-->" + * Print the patches that are applied: :: - sat config SALOME-8.4.0 --show_patchs + sat config SALOME-xx --show_patchs * Get information on a product configuration: :: - sat config --info - sat config SALOME-8.4.0 --info KERNEL - sat config SALOME-8.4.0 --info qt + # sat config --info + sat config SALOME-xx--info KERNEL + sat config SALOME-xx --info qt + +Some useful configuration pathes +================================= + +To know for exploring a current configuration. + +* PATHS: To get list of directories where to find files. + +* USER: To get user preferences (editor, pdf viewer, web browser, default working dir). + +sat commands: :: -Configuration -============= -* PATH. + sat config SALOME-xx -v PATHS + sat config SALOME-xx -v USERS - * **ARCHIVEPATH** list of directories where to find application files. - * **PRODUCTPATH** list of directories where to find products configuration files. -* USER - * **editor**: command to use to start an editor (by default vi), - * **browser**: command to use to start a browser (by default firefox), - * **pdf_viewer**: command to use to start a pdf viewer (by default evince). diff --git a/doc/src/commands/environ.rst b/doc/src/commands/environ.rst index 2646747..b3520b4 100644 --- a/doc/src/commands/environ.rst +++ b/doc/src/commands/environ.rst @@ -42,8 +42,9 @@ Usage It is useful when you want to visualise which environment uses sat to compile a given product. -Configuration -============= +Some useful configuration pathes +================================= + The specification of the environment can be done through sevaral mechanisms. 1. For salome products (the products with the property is_SALOME_module : "yes") the environment is set automatically by sat, in respect with Salomé requirements. diff --git a/doc/src/commands/launcher.rst b/doc/src/commands/launcher.rst index c67120a..93468f9 100644 --- a/doc/src/commands/launcher.rst +++ b/doc/src/commands/launcher.rst @@ -33,8 +33,10 @@ Usage This will create a catalog by querying each machine (memory, number of processor) with ssh. -Configuration -============= + +Some useful configuration pathes +================================= + * APPLICATION.profile * **product**: the name of the profile product (the product in charge of holding the application stuff, like logos, splashscreen) diff --git a/doc/src/commands/log.rst b/doc/src/commands/log.rst index 785905a..8f6e2e7 100644 --- a/doc/src/commands/log.rst +++ b/doc/src/commands/log.rst @@ -35,8 +35,9 @@ Usage -Configuration -============= +Some useful configuration pathes +================================= + * USER.browser * **browser**: The browser used to show the log (by default *firefox*). diff --git a/doc/src/commands/package.rst b/doc/src/commands/package.rst index bc6c6d2..4465f0a 100644 --- a/doc/src/commands/package.rst +++ b/doc/src/commands/package.rst @@ -9,14 +9,14 @@ Description The **package** command creates a SALOME_ archive (usually a compressed Tar_ file .tgz). This tar file is used later to intall SALOME on other remote computer. -Depending on the selected options, the created archive includes sources and binaries +Depending on the selected options, the archive includes sources and binaries of SALOME products and prerequisites. -Utility *salomeTools* is also included in the archive. +Usually utility *salomeTools* is included in the archive. .. note:: - By default the package only includes the sources of the prerequisites and the products. - To select a subset use the *--content* option. + By default the package includes the sources of prerequisites and products. + To select a subset use the *--without_property* or *--with_vcs* options. Usage @@ -25,9 +25,11 @@ Usage sat package SALOME_xx - This command will create an archive named ``SALOME_xx.tgz`` in the working directory (``$USER.workDir``). + This command will create an archive named ``SALOME_xx.tgz`` + in the working directory (``$USER.workDir``). If the archive already exists, do nothing. + * Create a package with a specific name: :: sat package SALOME_xx --name YourSpecificName @@ -35,9 +37,9 @@ Usage .. note:: By default, the archive is created in the working directory of the user (``$USER.workDir``). If the option *name* is used with a path (relative or absolute) it will be used. - If the option *name* is not used and binaries (modules or prerequisites) are - included in the package, the OS_ architecture (ex: *MD10_64*) - will be appended to the name. + If the option *name* is not used and binaries (prerequisites and products) are + included in the package, the OS_ architecture + will be appended to the name (example: *SALOME_xx-CO7.tgz*). Examples: :: @@ -49,11 +51,12 @@ Usage # Creates MySpecificName.tgz in $USER.workDir sat package SALOME_xx --name MySpecificName - - + + * Force the creation of the archive (if it already exists): :: - sat package SALOME_xx --force + sat package SALOME_xx --force + * Include the binaries in the archive (products and prerequisites): :: @@ -62,44 +65,15 @@ Usage This command will create an archive named ``SALOME_xx _.tgz`` where is the OS_ architecture of the machine. -* Set content of the archive: :: - - # only the prerequisites - sat package --content ps,pb - # only the modules sources - sat package --content ms - # only the binaries - sat package --content mb,pb - - - Possible values for content option are: - * ms: modules sources - * mb: modules binaries - * ps: prerequisites sources - * pb: prerequisites binaries - .. note:: this option is not compatible with the *--binaries* option. +* Do not delete Version Control System (VCS_) informations from the configurations files of the embedded salomeTools: :: + sat package --with_vcs -* Simulate the creation of the package (only check for required components): :: - - sat package --simulate - -* Do not include *sample* modules (like HELLO): :: - - sat package --no_sample - - Sample modules are identified by the ``$TOOLS.common.module_info..module_type`` parameter. - - By default salomeTools creates a copy of the installer with the same name than - the package. Use this option to not generate the installer. - -* Do not delete version control system informations from the configurations files of the embedded salomeTools: :: + The version control systems known by this option are CVS_, SVN_ and Git_. - sat package --with_vcs - The version control systems (vcs) taken into account by this option are CVS, SVN and Git. +Some useful configuration pathes +================================= -Configuration -============= No specific configuration. diff --git a/doc/src/commands/prepare.rst b/doc/src/commands/prepare.rst index f55b3c5..55755dc 100644 --- a/doc/src/commands/prepare.rst +++ b/doc/src/commands/prepare.rst @@ -60,8 +60,9 @@ Usage sat prepare --force_patch -Configuration -============= +Some useful configuration pathes +================================= + * sat prepare uses the pyconf configuration of each product to know how to get the sources. * **get_method**: the method to use to prepare the module, possible values are cvs, git, archive, dir. diff --git a/doc/src/conf.py b/doc/src/conf.py index 1a2fc74..14da019 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -28,7 +28,7 @@ import os # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc'] -# do not use rst_prolog please +# do not use rst_prolog please use doc/rst_prolog.rst and '.. include:: ../rst_prolog.rst' # https://github.com/sphinx-doc/sphinx/issues/2445 # Add any paths that contain templates here, relative to this directory. -- 2.39.2