From: Christian Van Wambeke Date: Thu, 12 Apr 2018 12:11:06 +0000 (+0200) Subject: fix doc/rst_prolog.rst avoid bug https://github.com/sphinx-doc/sphinx/issues/2445 X-Git-Tag: 5.1.0~39^2~5 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=922b9879b8b419e6e58d451214ff136871e9986d;p=tools%2Fsat.git fix doc/rst_prolog.rst avoid bug https://github.com/sphinx-doc/sphinx/issues/2445 --- diff --git a/commands/package.py b/commands/package.py index 5a2c493..e1126e0 100644 --- a/commands/package.py +++ b/commands/package.py @@ -1157,14 +1157,21 @@ def description(): :return: The text to display for the package command description. :rtype: str ''' - return _("The package command creates an archive.\nThere are 4 kinds of " - "archive, which can be mixed:\n 1- The binary archive. It contains all the product " - "installation directories and a launcher,\n 2- The sources archive." - " It contains the products archives, a project corresponding to " - "the application and salomeTools,\n 3- The project archive. It " - "contains a project (give the project file path as argument),\n 4-" - " The salomeTools archive. It contains salomeTools.\n\nexample:" - "\nsat package SALOME-master --bineries --sources") + return _(""" +The package command creates an tar archive of a product. +There are four kinds of archive, which can be mixed: + + 1 - The binary archive. + It contains the product installation directories plus a launcher. + 2 - The sources archive. + It contains the product archives, a project (the application plus salomeTools). + 3 - The project archive. + It contains a project (give the project file path as argument). + 4 - The salomeTools archive. + It contains code utility salomeTools. + +example: + >> sat package SALOME-master --binaries --sources""") def run(args, runner, logger): '''method that is called when salomeTools is called with package parameter. diff --git a/doc/rst_prolog.rst b/doc/rst_prolog.rst new file mode 100644 index 0000000..9ead7c9 --- /dev/null +++ b/doc/rst_prolog.rst @@ -0,0 +1,18 @@ + + +.. _SALOME: http://www.salome-platform.org +.. _SPHINX: http://sphinx-doc.org +.. _CAST3M: http://www-cast3m.cea.fr +.. _MATIX: ../../MATIX_PROFILE/doc/index.html +.. _C++: http://www.cplusplus.com/ +.. _CMake: https://cmake.org/ +.. _Python: https://docs.python.org/2.7 +.. _ParaView: http://www.paraview.org +.. _Anaconda: https://docs.continuum.io/anaconda/pkg-docs# +.. _Miniconda: http://conda.pydata.org/miniconda.html +.. _Git: https://git-scm.com +.. _GitCheatSheet: https://services.github.com/kit/downloads/github-git-cheat-sheet.pdf +.. _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 + diff --git a/doc/src/commands/clean.rst b/doc/src/commands/clean.rst new file mode 100644 index 0000000..33a0a7c --- /dev/null +++ b/doc/src/commands/clean.rst @@ -0,0 +1,110 @@ + +.. include:: ../../rst_prolog.rst + +Command clean +**************** + +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 + + 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. + +Configuration +============= +No specific configuration. diff --git a/doc/src/commands/environ.rst b/doc/src/commands/environ.rst index 6feb114..2646747 100644 --- a/doc/src/commands/environ.rst +++ b/doc/src/commands/environ.rst @@ -5,11 +5,13 @@ Command environ Description =========== The **environ** command generates the environment files used to run and compile SALOME. -Please note that these files are not required! SalomeTool set the environment himself, when compiling. +Please note that these files are not required any more, +salomeTool set the environment himself, when compiling. And so does the salome launcher. -These files are useful when one want to check the environment. -They are also used in debug mode to set the environment for gdb. -The configuration part at the end of this page explains how to specify the environment which will be used by sat (at build or run time), +These files are useful when someone wants to check the environment. +They could be used in debug mode to set the environment for gdb. +The configuration part at the end of this page explains how +to specify the environment which will be used by sat (at build or run time), and which is written in files by sat environ command. Usage diff --git a/doc/src/commands/package.rst b/doc/src/commands/package.rst new file mode 100644 index 0000000..bc6c6d2 --- /dev/null +++ b/doc/src/commands/package.rst @@ -0,0 +1,105 @@ + +.. include:: ../../rst_prolog.rst + +Command package +**************** + +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 +of SALOME products and prerequisites. + +Utility *salomeTools* is also 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. + + +Usage +===== +* Create a package for a product (example as *SALOME_xx*): :: + + sat package SALOME_xx + + 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 + +.. 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. + + Examples: :: + + # Creates SALOME_xx.tgz in $USER.workDir + sat package SALOME_xx + + # Creates SALOME_xx_.tgz in $USER.workDir + sat package SALOME_xx --binaries + + # 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 + +* Include the binaries in the archive (products and prerequisites): :: + + sat package SALOME_xx --binaries + + 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. + + +* 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. + +Configuration +============= +No specific configuration. diff --git a/doc/src/conf.py b/doc/src/conf.py index 71b983c..1a2fc74 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -28,6 +28,9 @@ import os # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc'] +# do not use rst_prolog please +# https://github.com/sphinx-doc/sphinx/issues/2445 + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -94,7 +97,6 @@ pygments_style = 'sphinx' # a list of builtin themes. # default sphinxdoc scrolls agogo traditional nature haiku html_theme = 'alabaster' -html_theme_path = ["../_themes/alabaster", ] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -102,7 +104,7 @@ html_theme_path = ["../_themes/alabaster", ] #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ["../_themes/alabaster", ] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -113,12 +115,12 @@ html_theme_path = ["../_themes/alabaster", ] # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +html_logo = "images/sat_v5.0.png" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -# html_favicon = "images/sat_v5_small.ico" +# html_favicon = "" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/src/images/sat_v5.0.png b/doc/src/images/sat_v5.0.png new file mode 100644 index 0000000..1057f5b Binary files /dev/null and b/doc/src/images/sat_v5.0.png differ diff --git a/doc/src/index.rst b/doc/src/index.rst index 882b8c9..8f88d09 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -1,16 +1,22 @@ + +.. include:: ../rst_prolog.rst + ************ -SAlome Tools +Salome Tools ************ .. note:: This documentation is under construction. -**SA**lome**T**ools (**sat**) is a suite of commands that can be used to perform operations -on SALOME. +The **Sa**\ lome\ **T**\ ools (sat) is a suite of commands +that can be used to perform operations on SALOME_. For example, sat allows you to compile SALOME's codes (prerequisites, products) create application, run tests, create package, etc. +This utility code is a set of Python_ scripts files. + + Quick start =========== @@ -34,6 +40,8 @@ List of Commands application log environ + clean + package Code documentation ================== diff --git a/doc/src/usage_of_sat.rst b/doc/src/usage_of_sat.rst index 0f6be19..80c7b46 100644 --- a/doc/src/usage_of_sat.rst +++ b/doc/src/usage_of_sat.rst @@ -1,10 +1,13 @@ + +.. include:: ../rst_prolog.rst + ******************** Usage of SAlomeTools ******************** Usage ===== -sat usage is a Command Line Interface (CLI). +sat usage is a Command Line Interface (CLI_). .. code-block:: bash diff --git a/doc/src/write_command.rst b/doc/src/write_command.rst index 726c553..adad305 100644 --- a/doc/src/write_command.rst +++ b/doc/src/write_command.rst @@ -1,9 +1,14 @@ -*************** -Write a command -*************** + + +Add a user custom command +*************************** Introduction ============ + +.. note:: This documentation is for python developers. + + The salomeTools product provides a simple way to develop commands. The first thing to do is to add a file with ".py" extension in the **commands** directory of salomeTools. @@ -141,4 +146,4 @@ Get the help of mycommand: Available options are: -m, --myoption (boolean) - My option changes the behavior of my command. \ No newline at end of file + My option changes the behavior of my command.