_("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
: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
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):
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):
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):
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
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 "
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)
: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 a tar file 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.
--- /dev/null
+
+# 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 &
+
--- /dev/null
+*.egg-info/
+build/
+dist/
+docs/_build
--- /dev/null
+language: python
+cache: pip
+python:
+ - "2.7"
+ - "3.4"
+ - "3.5"
+ - "3.6"
+ - "pypy"
+ - "pypy3"
+env:
+ - SPHINX=">=1.3,<1.4"
+ - SPHINX=">=1.4,<1.5"
+ - SPHINX=">=1.5,<1.6"
+ - SPHINX=">=1.6,<1.7"
+install:
+ # For some reason Travis' build envs have wildly different pip/setuptools
+ # versions between minor Python versions, and this can cause many hilarious
+ # corner packaging cases. So...
+ - pip install -U pip
+ # Setuptools 34+ seems to get less stable
+ - pip install 'setuptools>33,<34'
+ # Install dev requirements
+ - pip install -r dev-requirements.txt
+ # Limit Sphinx version re: test matrix
+ - pip install "sphinx$SPHINX"
+ # Sanity/debug-friendliness: list what got installed
+ - pip list --format=columns
+ # Dev tooling sanity test: can invoke list tasks?
+ - inv --list
+script:
+ # We have no real tests at present so we just make sure installation works,
+ # first off.
+ - pip install .
+ # Does our own dogfooding website build ok? :D
+ - inv docs
+ # I have this in my git pre-push hook, but contributors probably don't
+ - flake8
--- /dev/null
+Copyright (c) 2018 Jeff Forcier.
+
+Based on original work copyright (c) 2011 Kenneth Reitz and copyright (c) 2010
+Armin Ronacher.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms of the theme, with or
+without modification, are permitted provided that the following conditions
+are met:
+
+* Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+* 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.
+
+* The names of the contributors may not be used to endorse or
+ promote products derived from this software without specific
+ prior written permission.
+
+THIS THEME 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 OWNER 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 THEME, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
--- /dev/null
+include LICENSE
+include README.md
+recursive-include alabaster *.*
+recursive-exclude alabaster .*.swp
--- /dev/null
+What is Alabaster?
+==================
+
+Alabaster is a visually (c)lean, responsive, configurable theme for the `Sphinx
+<http://sphinx-doc.org>`_ documentation system. It is Python 2+3 compatible.
+
+It began as a third-party theme, and is still maintained separately, but as of
+Sphinx 1.3, Alabaster is an install-time dependency of Sphinx and is selected
+as the default theme.
+
+Live examples of this theme can be seen on `this project's own website
+<http://alabaster.readthedocs.io>`_, `paramiko.org <http://paramiko.org>`_,
+`fabfile.org <http://fabfile.org>`_ and `pyinvoke.org <http://pyinvoke.org>`_.
+
+For more documentation, please see http://alabaster.readthedocs.io.
+
+.. note::
+ You can install the development version via ``pip install -e
+ git+https://github.com/bitprophet/alabaster/#egg=alabaster``.
--- /dev/null
+import os
+
+from alabaster import _version as version
+
+
+def get_path():
+ """
+ Shortcut for users whose theme is next to their conf.py.
+ """
+ # Theme directory is defined as our parent directory
+ return os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
+
+
+def update_context(app, pagename, templatename, context, doctree):
+ context['alabaster_version'] = version.__version__
+
+def setup(app):
+ # add_html_theme is new in Sphinx 1.6+
+ if hasattr(app, 'add_html_theme'):
+ theme_path = os.path.abspath(os.path.dirname(__file__))
+ app.add_html_theme('alabaster', theme_path)
+ app.connect('html-page-context', update_context)
+ return {'version': version.__version__,
+ 'parallel_read_safe': True}
--- /dev/null
+__version_info__ = (0, 7, 10)
+__version__ = '.'.join(map(str, __version_info__))
--- /dev/null
+{% if theme_logo %}
+<p class="logo">
+ <a href="{{ pathto(master_doc) }}">
+ <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo"/>
+ {% if theme_logo_name|lower == 'true' %}
+ <h1 class="logo logo-name">{{ project }}</h1>
+ {% endif %}
+ </a>
+</p>
+{% else %}
+<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>
+{% endif %}
+
+{% if theme_description %}
+<p class="blurb">{{ theme_description }}</p>
+{% endif %}
+
+{% if theme_github_user and theme_github_repo %}
+{% if theme_github_button|lower == 'true' %}
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user={{ theme_github_user }}&repo={{ theme_github_repo }}&type={{ theme_github_type }}&count={{ theme_github_count }}&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+{% endif %}
+{% endif %}
+
+{% if theme_travis_button|lower != 'false' %}
+{% if theme_travis_button|lower == 'true' %}
+ {% set path = theme_github_user + '/' + theme_github_repo %}
+{% else %}
+ {% set path = theme_travis_button %}
+{% endif %}
+<p>
+<a href="https://travis-ci.org/{{ path }}">
+ <img
+ alt="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
+ src="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
+ />
+</a>
+</p>
+{% endif %}
+
+{% if theme_codecov_button|lower != 'false' %}
+{% if theme_codecov_button|lower == 'true' %}
+ {% set path = theme_github_user + '/' + theme_github_repo %}
+{% else %}
+ {% set path = theme_codecov_button %}
+{% endif %}
+<p>
+<a href="https://codecov.io/github/{{ path }}">
+ <img
+ alt="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
+ src="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
+ />
+</a>
+</p>
+{% endif %}
--- /dev/null
+{% if theme_gratipay_user or theme_gittip_user %}
+<h3>Donate</h3>
+<p>
+Consider supporting the authors on <a href="https://www.gratipay.com/">Gratipay</a>:
+<script data-gratipay-username="{{ theme_gratipay_user or theme_gittip_user }}"
+ data-gratipay-widget="button"
+ src="//gttp.co/v1.js"></script>
+</p>
+{% endif %}
--- /dev/null
+{%- extends "basic/layout.html" %}
+
+{%- block extrahead %}
+ {{ super() }}
+ <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}" type="text/css" />
+ {% if theme_touch_icon %}
+ <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
+ {% endif %}
+ {% if theme_canonical_url %}
+ <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html"/>
+ {% endif %}
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+{% endblock %}
+
+{# Disable base theme's top+bottom related navs; we have our own in sidebar #}
+{%- block relbar1 %}{% endblock %}
+{%- block relbar2 %}{% endblock %}
+
+{# Nav should appear before content, not after #}
+{%- block content %}
+{%- if theme_fixed_sidebar|lower == 'true' %}
+ <div class="document">
+ {{ sidebar() }}
+ {%- block document %}
+ <div class="documentwrapper">
+ {%- if render_sidebar %}
+ <div class="bodywrapper">
+ {%- endif %}
+ <div class="body" role="main">
+ {% block body %} {% endblock %}
+ </div>
+ {%- if render_sidebar %}
+ </div>
+ {%- endif %}
+ </div>
+ {%- endblock %}
+ <div class="clearer"></div>
+ </div>
+{%- else %}
+{{ super() }}
+{%- endif %}
+{%- endblock %}
+
+{%- block footer %}
+ <div class="footer">
+ {% if show_copyright %}©{{ copyright }}.{% endif %}
+ {% if theme_show_powered_by|lower == 'true' %}
+ {% if show_copyright %}|{% endif %}
+ Powered by <a href="http://sphinx-doc.org/">Sphinx {{ sphinx_version }}</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster {{ alabaster_version }}</a>
+ {% endif %}
+ {%- if show_source and has_source and sourcename %}
+ {% if show_copyright or theme_show_powered_by %}|{% endif %}
+ <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+ rel="nofollow">{{ _('Page source') }}</a>
+ {%- endif %}
+ </div>
+
+ {% if theme_github_banner|lower != 'false' %}
+ <a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}" class="github">
+ <img style="position: absolute; top: 0; right: 0; border: 0;" src="{{ pathto('_static/' ~ theme_github_banner, 1) if theme_github_banner|lower != 'true' else 'https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png' }}" alt="Fork me on GitHub" class="github"/>
+ </a>
+ {% endif %}
+
+ {% if theme_analytics_id %}
+ <script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', '{{ theme_analytics_id }}']);
+ _gaq.push(['_setDomainName', 'none']);
+ _gaq.push(['_setAllowLinker', true]);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+ </script>
+ {% endif %}
+{%- endblock %}
--- /dev/null
+<h3>{{ _('Navigation') }}</h3>
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+ {% for text, uri in theme_extra_nav_links.items() %}
+ <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+ {% endfor %}
+</ul>
+{% endif %}
--- /dev/null
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
+ {%- for parent in parents %}
+ <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
+ {%- endfor %}
+ {%- if prev %}
+ <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
+ }}">{{ prev.title }}</a></li>
+ {%- endif %}
+ {%- if next %}
+ <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
+ }}">{{ next.title }}</a></li>
+ {%- endif %}
+ {%- for parent in parents %}
+ </ul></li>
+ {%- endfor %}
+ </ul></li>
+</ul>
+</div>
--- /dev/null
+{% set theme_body_bg = theme_body_bg or theme_base_bg %}
+{% set theme_code_highlight_bg = theme_code_highlight_bg or theme_body_bg %}
+{% set theme_sidebar_header = theme_sidebar_header or theme_gray_1 %}
+{% set theme_sidebar_link = theme_sidebar_link or theme_gray_1 %}
+{% set theme_anchor_hover_fg = theme_anchor_hover_fg or theme_gray_1 %}
+
+{% set theme_footnote_border = theme_footnote_border or theme_gray_2 %}
+{% set theme_pre_bg = theme_pre_bg or theme_gray_2 %}
+
+
+{# set up admonition styling #}
+{# - basic level #}
+{% set theme_admonition_xref_bg = theme_admonition_xref_bg or theme_xref_bg %}
+{% set theme_admonition_bg = theme_admonition_bg or theme_gray_2 %}
+{% set theme_note_bg = theme_note_bg or theme_gray_2 %}
+{% set theme_seealso_bg = theme_seealso_bg or theme_gray_2 %}
+
+{# - critical level #}
+{% set theme_danger_bg = theme_danger_bg or theme_pink_1 %}
+{% set theme_danger_border = theme_danger_border or theme_pink_2 %}
+{% set theme_danger_shadow = theme_danger_shadow or theme_pink_3 %}
+
+{% set theme_error_bg = theme_error_bg or theme_pink_1 %}
+{% set theme_error_border = theme_error_border or theme_pink_2 %}
+{% set theme_error_shadow = theme_error_shadow or theme_pink_3 %}
+
+{# - warning level #}
+{% set theme_caution_bg = theme_caution_bg or theme_pink_1 %}
+{% set theme_caution_border = theme_caution_border or theme_pink_2 %}
+
+{% set theme_attention_bg = theme_attention_bg or theme_pink_1 %}
+{% set theme_attention_border = theme_attention_border or theme_pink_2 %}
+
+{% set theme_warn_bg = theme_warn_bg or theme_pink_1 %}
+{% set theme_warn_border = theme_warn_border or theme_pink_2 %}
+
+{# - normal level #}
+{% set theme_important_bg = theme_important_bg or theme_gray_2 %}
+{% set theme_tip_bg = theme_tip_bg or theme_gray_2 %}
+{% set theme_hint_bg = theme_hint_bg or theme_gray_2 %}
+
+{# /set up admonition styling #}
+
+{% set theme_shadow = theme_shadow or theme_gray_2 %}
+
+
+{% set theme_topic_bg = theme_topic_bg or theme_gray_2 %}
+
+{% set theme_narrow_sidebar_link = theme_narrow_sidebar_link or theme_gray_3 %}
+{% set theme_sidebar_hr = theme_sidebar_hr or theme_gray_3 %}
+
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+ font-family: {{ theme_font_family }};
+ font-size: {{ theme_font_size }};
+ background-color: {{ theme_base_bg }};
+ color: {{ theme_base_text }};
+ margin: 0;
+ padding: 0;
+}
+
+
+div.document {
+ width: {{ theme_page_width }};
+ margin: 30px auto 0 auto;
+}
+
+div.documentwrapper {
+ float: left;
+ width: 100%;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 {{ theme_sidebar_width }};
+}
+
+div.sphinxsidebar {
+ width: {{ theme_sidebar_width }};
+ font-size: 14px;
+ line-height: 1.5;
+}
+
+hr {
+ border: 1px solid {{ theme_hr_border }};
+}
+
+div.body {
+ background-color: {{ theme_body_bg }};
+ color: {{ theme_body_text }};
+ padding: 0 30px 0 30px;
+}
+
+div.body > .section {
+ text-align: {{ theme_body_text_align }};
+}
+
+div.footer {
+ width: {{ theme_page_width }};
+ margin: 20px auto 30px auto;
+ font-size: 14px;
+ color: {{ theme_footer_text }};
+ text-align: right;
+}
+
+div.footer a {
+ color: {{ theme_footer_text }};
+}
+
+p.caption {
+ font-family: {{ theme_caption_font_family }};
+ font-size: {{ theme_caption_font_size }};
+}
+
+{% if theme_show_related|lower == 'false' %}
+div.relations {
+ display: none;
+}
+{% endif %}
+
+div.sphinxsidebar a {
+ color: {{ theme_sidebar_link }};
+ text-decoration: none;
+ border-bottom: 1px dotted {{ theme_sidebar_link_underscore }};
+}
+
+div.sphinxsidebar a:hover {
+ border-bottom: 1px solid {{ theme_sidebar_link_underscore }};
+}
+
+div.sphinxsidebarwrapper {
+ padding: 18px 10px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+ padding: 0;
+ margin: -10px 0 0 0px;
+ text-align: center;
+}
+
+div.sphinxsidebarwrapper h1.logo {
+ margin-top: -10px;
+ text-align: center;
+ margin-bottom: 5px;
+ text-align: {{ theme_logo_text_align }};
+}
+
+div.sphinxsidebarwrapper h1.logo-name {
+ margin-top: 0px;
+}
+
+div.sphinxsidebarwrapper p.blurb {
+ margin-top: 0;
+ font-style: {{ theme_description_font_style }};
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ font-family: {{ theme_head_font_family }};
+ color: {{ theme_sidebar_header }};
+ font-size: 24px;
+ font-weight: normal;
+ margin: 0 0 5px 0;
+ padding: 0;
+}
+
+div.sphinxsidebar h4 {
+ font-size: 20px;
+}
+
+div.sphinxsidebar h3 a {
+ color: {{ theme_sidebar_link }};
+}
+
+div.sphinxsidebar p.logo a,
+div.sphinxsidebar h3 a,
+div.sphinxsidebar p.logo a:hover,
+div.sphinxsidebar h3 a:hover {
+ border: none;
+}
+
+div.sphinxsidebar p {
+ color: {{ theme_sidebar_text }};
+ margin: 10px 0;
+}
+
+div.sphinxsidebar ul {
+ margin: 10px 0;
+ padding: 0;
+ color: {{ theme_sidebar_list }};
+}
+
+div.sphinxsidebar ul li.toctree-l1 > a {
+ font-size: 120%;
+}
+
+div.sphinxsidebar ul li.toctree-l2 > a {
+ font-size: 110%;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid {{ theme_sidebar_search_button }};
+ font-family: {{ theme_font_family }};
+ font-size: 1em;
+}
+
+div.sphinxsidebar hr {
+ border: none;
+ height: 1px;
+ color: {{ theme_sidebar_hr }};
+ background: {{ theme_sidebar_hr }};
+
+ text-align: left;
+ margin-left: 0;
+ width: 50%;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+ color: {{ theme_link }};
+ text-decoration: underline;
+}
+
+a:hover {
+ color: {{ theme_link_hover }};
+ text-decoration: underline;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+ font-family: {{ theme_head_font_family }};
+ font-weight: normal;
+ margin: 30px 0px 10px 0px;
+ padding: 0;
+}
+
+div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
+div.body h2 { font-size: 180%; }
+div.body h3 { font-size: 150%; }
+div.body h4 { font-size: 130%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+ color: {{ theme_anchor }};
+ padding: 0 4px;
+ text-decoration: none;
+}
+
+a.headerlink:hover {
+ color: {{ theme_anchor_hover_fg }};
+ background: {{ theme_anchor_hover_bg }};
+}
+
+div.body p, div.body dd, div.body li {
+ line-height: 1.4em;
+}
+
+div.admonition {
+ margin: 20px 0px;
+ padding: 10px 30px;
+ background-color: {{ theme_admonition_bg }};
+ border: 1px solid {{ theme_admonition_border }};
+}
+
+div.admonition tt.xref, div.admonition code.xref, div.admonition a tt {
+ background-color: {{ theme_admonition_xref_bg }};
+ border-bottom: 1px solid {{ theme_admonition_xref_border }};
+}
+
+div.admonition p.admonition-title {
+ font-family: {{ theme_head_font_family }};
+ font-weight: normal;
+ font-size: 24px;
+ margin: 0 0 10px 0;
+ padding: 0;
+ line-height: 1;
+}
+
+div.admonition p.last {
+ margin-bottom: 0;
+}
+
+div.highlight {
+ background-color: {{ theme_code_highlight_bg }};
+}
+
+dt:target, .highlight {
+ background: {{ theme_highlight_bg }};
+}
+
+div.warning {
+ background-color: {{ theme_warn_bg }};
+ border: 1px solid {{ theme_warn_border }};
+}
+
+div.danger {
+ background-color: {{ theme_danger_bg }};
+ border: 1px solid {{ theme_danger_border }};
+ -moz-box-shadow: 2px 2px 4px {{ theme_danger_shadow }};
+ -webkit-box-shadow: 2px 2px 4px {{ theme_danger_shadow }};
+ box-shadow: 2px 2px 4px {{ theme_danger_shadow }};
+}
+
+div.error {
+ background-color: {{ theme_error_bg }};
+ border: 1px solid {{ theme_error_border }};
+ -moz-box-shadow: 2px 2px 4px {{ theme_error_shadow }};
+ -webkit-box-shadow: 2px 2px 4px {{ theme_error_shadow }};
+ box-shadow: 2px 2px 4px {{ theme_error_shadow }};
+}
+
+div.caution {
+ background-color: {{ theme_caution_bg }};
+ border: 1px solid {{ theme_caution_border }};
+}
+
+div.attention {
+ background-color: {{ theme_attention_bg }};
+ border: 1px solid {{ theme_attention_border }};
+}
+
+div.important {
+ background-color: {{ theme_important_bg }};
+ border: 1px solid {{ theme_important_border }};
+}
+
+div.note {
+ background-color: {{ theme_note_bg }};
+ border: 1px solid {{ theme_note_border }};
+}
+
+div.tip {
+ background-color: {{ theme_tip_bg }};
+ border: 1px solid {{ theme_tip_border }};
+}
+
+div.hint {
+ background-color: {{ theme_hint_bg }};
+ border: 1px solid {{ theme_hint_border }};
+}
+
+div.seealso {
+ background-color: {{ theme_seealso_bg }};
+ border: 1px solid {{ theme_seealso_border }};
+}
+
+div.topic {
+ background-color: {{ theme_topic_bg }};
+}
+
+p.admonition-title {
+ display: inline;
+}
+
+p.admonition-title:after {
+ content: ":";
+}
+
+pre, tt, code {
+ font-family: {{theme_code_font_family}};
+ font-size: {{ theme_code_font_size }};
+}
+
+.hll {
+ background-color: {{theme_code_highlight}};
+ margin: 0 -12px;
+ padding: 0 12px;
+ display: block;
+}
+
+img.screenshot {
+}
+
+tt.descname, tt.descclassname, code.descname, code.descclassname {
+ font-size: 0.95em;
+}
+
+tt.descname, code.descname {
+ padding-right: 0.08em;
+}
+
+img.screenshot {
+ -moz-box-shadow: 2px 2px 4px {{ theme_shadow }};
+ -webkit-box-shadow: 2px 2px 4px {{ theme_shadow }};
+ box-shadow: 2px 2px 4px {{ theme_shadow }};
+}
+
+table.docutils {
+ border: 1px solid {{ theme_table_border }};
+ -moz-box-shadow: 2px 2px 4px {{ theme_shadow }};
+ -webkit-box-shadow: 2px 2px 4px {{ theme_shadow }};
+ box-shadow: 2px 2px 4px {{ theme_shadow }};
+}
+
+table.docutils td, table.docutils th {
+ border: 1px solid {{ theme_table_border }};
+ padding: 0.25em 0.7em;
+}
+
+table.field-list, table.footnote {
+ border: none;
+ -moz-box-shadow: none;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+}
+
+table.footnote {
+ margin: 15px 0;
+ width: 100%;
+ border: 1px solid {{ theme_footnote_border }};
+ background: {{ theme_footnote_bg }};
+ font-size: 0.9em;
+}
+
+table.footnote + table.footnote {
+ margin-top: -15px;
+ border-top: none;
+}
+
+table.field-list th {
+ padding: 0 0.8em 0 0;
+}
+
+table.field-list td {
+ padding: 0;
+}
+
+table.field-list p {
+ margin-bottom: 0.8em;
+}
+
+/* Cloned from
+ * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68
+ */
+.field-name {
+ -moz-hyphens: manual;
+ -ms-hyphens: manual;
+ -webkit-hyphens: manual;
+ hyphens: manual;
+}
+
+table.footnote td.label {
+ width: .1px;
+ padding: 0.3em 0 0.3em 0.5em;
+}
+
+table.footnote td {
+ padding: 0.3em 0.5em;
+}
+
+dl {
+ margin: 0;
+ padding: 0;
+}
+
+dl dd {
+ margin-left: 30px;
+}
+
+blockquote {
+ margin: 0 0 0 30px;
+ padding: 0;
+}
+
+ul, ol {
+ /* Matches the 30px from the narrow-screen "li > ul" selector below */
+ margin: 10px 0 10px 30px;
+ padding: 0;
+}
+
+pre {
+ background: {{ theme_pre_bg }};
+ padding: 7px 30px;
+ margin: 15px 0px;
+ line-height: 1.3em;
+}
+
+div.viewcode-block:target {
+ background: {{ theme_viewcode_target_bg }};
+}
+
+dl pre, blockquote pre, li pre {
+ margin-left: 0;
+ padding-left: 30px;
+}
+
+tt, code {
+ background-color: {{ theme_code_bg }};
+ color: {{ theme_code_text }};
+ /* padding: 1px 2px; */
+}
+
+tt.xref, code.xref, a tt {
+ background-color: {{ theme_xref_bg }};
+ border-bottom: 1px solid {{ theme_xref_border }};
+}
+
+a.reference {
+ text-decoration: none;
+ border-bottom: 1px dotted {{ theme_link }};
+}
+
+/* Don't put an underline on images */
+a.image-reference, a.image-reference:hover {
+ border-bottom: none;
+}
+
+a.reference:hover {
+ border-bottom: 1px solid {{ theme_link_hover }};
+}
+
+a.footnote-reference {
+ text-decoration: none;
+ font-size: 0.7em;
+ vertical-align: top;
+ border-bottom: 1px dotted {{ theme_link }};
+}
+
+a.footnote-reference:hover {
+ border-bottom: 1px solid {{ theme_link_hover }};
+}
+
+a:hover tt, a:hover code {
+ background: {{ theme_code_hover }};
+}
+
+
+@media screen and (max-width: 870px) {
+
+ div.sphinxsidebar {
+ display: none;
+ }
+
+ div.document {
+ width: 100%;
+
+ }
+
+ div.documentwrapper {
+ margin-left: 0;
+ margin-top: 0;
+ margin-right: 0;
+ margin-bottom: 0;
+ }
+
+ div.bodywrapper {
+ margin-top: 0;
+ margin-right: 0;
+ margin-bottom: 0;
+ margin-left: 0;
+ }
+
+ ul {
+ margin-left: 0;
+ }
+
+ li > ul {
+ /* Matches the 30px from the "ul, ol" selector above */
+ margin-left: 30px;
+ }
+
+ .document {
+ width: auto;
+ }
+
+ .footer {
+ width: auto;
+ }
+
+ .bodywrapper {
+ margin: 0;
+ }
+
+ .footer {
+ width: auto;
+ }
+
+ .github {
+ display: none;
+ }
+
+
+
+}
+
+
+
+@media screen and (max-width: 875px) {
+
+ body {
+ margin: 0;
+ padding: 20px 30px;
+ }
+
+ div.documentwrapper {
+ float: none;
+ background: {{ theme_base_bg }};
+ }
+
+ div.sphinxsidebar {
+ display: block;
+ float: none;
+ width: 102.5%;
+ {%- if theme_fixed_sidebar|lower == 'true' %}
+ margin: -20px -30px 20px -30px;
+ {%- else %}
+ margin: 50px -30px -20px -30px;
+ {%- endif %}
+ padding: 10px 20px;
+ background: {{ theme_narrow_sidebar_bg }};
+ color: {{ theme_narrow_sidebar_fg }};
+ }
+
+ div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
+ div.sphinxsidebar h3 a {
+ color: {{ theme_base_bg }};
+ }
+
+ div.sphinxsidebar a {
+ color: {{ theme_narrow_sidebar_link }};
+ }
+
+ div.sphinxsidebar p.logo {
+ display: none;
+ }
+
+ div.document {
+ width: 100%;
+ margin: 0;
+ }
+
+ div.footer {
+ display: none;
+ }
+
+ div.bodywrapper {
+ margin: 0;
+ }
+
+ div.body {
+ min-height: 0;
+ padding: 0;
+ }
+
+ .rtd_doc_footer {
+ display: none;
+ }
+
+ .document {
+ width: auto;
+ }
+
+ .footer {
+ width: auto;
+ }
+
+ .footer {
+ width: auto;
+ }
+
+ .github {
+ display: none;
+ }
+}
+
+{%- if theme_fixed_sidebar|lower == 'true' %}
+@media screen and (min-width: 876px) {
+ div.sphinxsidebar {
+ position: fixed;
+ margin-left: 0;
+ }
+}
+{%- endif %}
+
+
+/* misc. */
+
+.revsys-inline {
+ display: none!important;
+}
+
+/* Make nested-list/multi-paragraph items look better in Releases changelog
+ * pages. Without this, docutils' magical list fuckery causes inconsistent
+ * formatting between different release sub-lists.
+ */
+div#changelog > div.section > ul > li > p:only-child {
+ margin-bottom: 0;
+}
+
+/* Hide fugly table cell borders in ..bibliography:: directive output */
+table.docutils.citation, table.docutils.citation td, table.docutils.citation th {
+ border: none;
+ /* Below needed in some edge cases; if not applied, bottom shadows appear */
+ -moz-box-shadow: none;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+}
--- /dev/null
+/* This file intentionally left blank. */
+
+/*
+http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+set backquotes: ``text`` for code samples more color red
+*/
+
+tt, code {
+ background-color: #ecf0f3;
+ color: #842;
+ /* padding: 1px 2px; */
+}
+
--- /dev/null
+# flake8: noqa
+
+from pygments.style import Style
+from pygments.token import Keyword, Name, Comment, String, Error, \
+ Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
+
+
+# Originally based on FlaskyStyle which was based on 'tango'.
+class Alabaster(Style):
+ background_color = "#f8f8f8" # doesn't seem to override CSS 'pre' styling?
+ default_style = ""
+
+ styles = {
+ # No corresponding class for the following:
+ #Text: "", # class: ''
+ Whitespace: "underline #f8f8f8", # class: 'w'
+ Error: "#a40000 border:#ef2929", # class: 'err'
+ Other: "#000000", # class 'x'
+
+ Comment: "italic #8f5902", # class: 'c'
+ Comment.Preproc: "noitalic", # class: 'cp'
+
+ Keyword: "bold #004461", # class: 'k'
+ Keyword.Constant: "bold #004461", # class: 'kc'
+ Keyword.Declaration: "bold #004461", # class: 'kd'
+ Keyword.Namespace: "bold #004461", # class: 'kn'
+ Keyword.Pseudo: "bold #004461", # class: 'kp'
+ Keyword.Reserved: "bold #004461", # class: 'kr'
+ Keyword.Type: "bold #004461", # class: 'kt'
+
+ Operator: "#582800", # class: 'o'
+ Operator.Word: "bold #004461", # class: 'ow' - like keywords
+
+ Punctuation: "bold #000000", # class: 'p'
+
+ # because special names such as Name.Class, Name.Function, etc.
+ # are not recognized as such later in the parsing, we choose them
+ # to look the same as ordinary variables.
+ Name: "#000000", # class: 'n'
+ Name.Attribute: "#c4a000", # class: 'na' - to be revised
+ Name.Builtin: "#004461", # class: 'nb'
+ Name.Builtin.Pseudo: "#3465a4", # class: 'bp'
+ Name.Class: "#000000", # class: 'nc' - to be revised
+ Name.Constant: "#000000", # class: 'no' - to be revised
+ Name.Decorator: "#888", # class: 'nd' - to be revised
+ Name.Entity: "#ce5c00", # class: 'ni'
+ Name.Exception: "bold #cc0000", # class: 'ne'
+ Name.Function: "#000000", # class: 'nf'
+ Name.Property: "#000000", # class: 'py'
+ Name.Label: "#f57900", # class: 'nl'
+ Name.Namespace: "#000000", # class: 'nn' - to be revised
+ Name.Other: "#000000", # class: 'nx'
+ Name.Tag: "bold #004461", # class: 'nt' - like a keyword
+ Name.Variable: "#000000", # class: 'nv' - to be revised
+ Name.Variable.Class: "#000000", # class: 'vc' - to be revised
+ Name.Variable.Global: "#000000", # class: 'vg' - to be revised
+ Name.Variable.Instance: "#000000", # class: 'vi' - to be revised
+
+ Number: "#990000", # class: 'm'
+
+ Literal: "#000000", # class: 'l'
+ Literal.Date: "#000000", # class: 'ld'
+
+ String: "#4e9a06", # class: 's'
+ String.Backtick: "#4e9a06", # class: 'sb'
+ String.Char: "#4e9a06", # class: 'sc'
+ String.Doc: "italic #8f5902", # class: 'sd' - like a comment
+ String.Double: "#4e9a06", # class: 's2'
+ String.Escape: "#4e9a06", # class: 'se'
+ String.Heredoc: "#4e9a06", # class: 'sh'
+ String.Interpol: "#4e9a06", # class: 'si'
+ String.Other: "#4e9a06", # class: 'sx'
+ String.Regex: "#4e9a06", # class: 'sr'
+ String.Single: "#4e9a06", # class: 's1'
+ String.Symbol: "#4e9a06", # class: 'ss'
+
+ Generic: "#000000", # class: 'g'
+ Generic.Deleted: "#a40000", # class: 'gd'
+ Generic.Emph: "italic #000000", # class: 'ge'
+ Generic.Error: "#ef2929", # class: 'gr'
+ Generic.Heading: "bold #000080", # class: 'gh'
+ Generic.Inserted: "#00A000", # class: 'gi'
+ Generic.Output: "#888", # class: 'go'
+ Generic.Prompt: "#745334", # class: 'gp'
+ Generic.Strong: "bold #000000", # class: 'gs'
+ Generic.Subheading: "bold #800080", # class: 'gu'
+ Generic.Traceback: "bold #a40000", # class: 'gt'
+ }
--- /dev/null
+[theme]
+inherit = basic
+stylesheet = alabaster.css
+pygments_style = alabaster.support.Alabaster
+
+[options]
+logo =
+logo_name = false
+logo_text_align = left
+description =
+description_font_style = normal
+github_user =
+github_repo =
+github_button = true
+github_banner = false
+github_type = watch
+github_count = true
+badge_branch = master
+travis_button = false
+codecov_button = false
+gratipay_user =
+gittip_user =
+analytics_id =
+touch_icon =
+canonical_url =
+extra_nav_links =
+sidebar_includehidden = true
+sidebar_collapse = true
+show_powered_by = true
+show_related = false
+
+gray_1 = #444
+gray_2 = #EEE
+gray_3 = #AAA
+
+pink_1 = #FCC
+pink_2 = #FAA
+pink_3 = #D52C2C
+
+base_bg = #fff
+base_text = #000
+hr_border = #B1B4B6
+body_bg =
+body_text = #3E4349
+body_text_align = left
+footer_text = #888
+link = #004B6B
+link_hover = #6D4100
+sidebar_header =
+sidebar_text = #555
+sidebar_link =
+sidebar_link_underscore = #999
+sidebar_search_button = #CCC
+sidebar_list = #000
+sidebar_hr =
+anchor = #DDD
+anchor_hover_fg =
+anchor_hover_bg = #EAEAEA
+table_border = #888
+shadow =
+
+# Admonition options
+## basic level
+admonition_bg =
+admonition_border = #CCC
+note_bg =
+note_border = #CCC
+seealso_bg =
+seealso_border = #CCC
+
+## critical level
+danger_bg =
+danger_border =
+danger_shadow =
+error_bg =
+error_border =
+error_shadow =
+
+## normal level
+tip_bg =
+tip_border = #CCC
+hint_bg =
+hint_border = #CCC
+important_bg =
+important_border = #CCC
+
+## warning level
+caution_bg =
+caution_border =
+attention_bg =
+attention_border =
+warn_bg =
+warn_border =
+
+topic_bg =
+code_highlight_bg =
+highlight_bg = #FAF3E8
+xref_border = #fff
+xref_bg = #FBFBFB
+admonition_xref_border = #fafafa
+admonition_xref_bg =
+footnote_bg = #FDFDFD
+footnote_border =
+pre_bg =
+narrow_sidebar_bg = #333
+narrow_sidebar_fg = #FFF
+narrow_sidebar_link =
+font_size = 17px
+caption_font_size = inherit
+viewcode_target_bg = #ffd
+code_bg = #ecf0f3
+code_text = #222
+code_hover = #EEE
+code_font_size = 0.9em
+code_font_family = 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace
+font_family = 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif
+head_font_family = 'Garamond', 'Georgia', serif
+caption_font_family = inherit
+code_highlight = #FFC
+page_width = 940px
+sidebar_width = 220px
+fixed_sidebar = false
--- /dev/null
+sphinx>=1.3
+invoke>=0.10.1
+invocations>=0.6.2
+semantic_version>=2.4,<2.5
+wheel==0.24
+twine==1.11.0
+releases>=1.2.0,<2.0
+flake8==2.4.0
--- /dev/null
+=========
+Changelog
+=========
+
+* :support:`- backported` Miscellaneous project maintenance updates such as
+ adding to Travis CI and enforcing the use of ``flake8``.
+* :feature:`110 backported` Add ``badge_branch`` option allowing
+ configurability of which specific Git branch the Travis, Codecov, etc buttons
+ default to. Credit: ``@TitanSnow``.
+* :support:`111 backported` Add setuptools-level entrypoint for improved theme
+ distribution compatibility. Thanks to Aaron Carlisle for the patch.
+* :release:`0.7.10 <2017-02-28>`
+* :bug:`32` Update styling of various block-level elements such as admonitions
+ (``.. note::``, ``.. warning::``, etc) and code blocks (``.. code::``) so
+ they are no longer 'dedented' outside the main column of text they're
+ embedded in. This is both a stylistic change and a bugfix, since e.g. nesting
+ code blocks *within* note blocks looks actively broken. Thanks to Takayuki
+ Shimizukawa for the report.
+* :bug:`96` ``admonition_xref`` had a template typo preventing it from
+ receiving styling; this has been fixed. Credit: Kenzie Togami.
+* :bug:`95` Independently ran across
+ `sphinx-doc/sphinx#3276 <https://github.com/sphinx-doc/sphinx/issues/3276>`_,
+ namely that parameter lists become squashed together if one is running on
+ Sphinx 1.4.x. While that fix was merged in Sphinx itself, we felt it prudent
+ to include it in our own stylesheet as well, for immediate relief.
+* :release:`0.7.9 <2016-07-25>`
+* :feature:`6` (and :issue:`70`, both via :issue:`84`) Make all remaining
+ hardcoded style colors configurable, plus related cleanup (such as improving
+ differentiation of some admonition blocks such as ``warn`` and ``note``,
+ ensuring generic admonitions are left untouched, etc). Credit:
+ ``@ShadowKyogre``.
+* :feature:`83` Expose Sphinx's toctree ``collapse`` option as the new
+ ``sidebar_collapse`` config option. Credit: Eric Holscher.
+* :feature:`80` Add support for ``<link rel="canonical">`` (i.e. canonical
+ URLs). Thanks to Ben Gamari for the patch.
+* :support:`7` Generate real documentation site, both because the README is
+ just too big now, and so we can `eat our own dog food
+ <https://en.wikipedia.org/wiki/Eating_your_own_dog_food>`_.
+* :release:`0.7.8 <2016-05-05>`
+* #51 (via #67): Hide Github button if ``github_user`` and ``github_repo``
+ aren't set. This is necessary since ``github_button`` defaults to True.
+ Thanks to Sam Whited for the report & Dmitry Shachnev for the patch.
+* #75: Use SVG version of the Travis-CI button. Thanks to Sebastian Wiesner for
+ the patch.
+* #41: Update the Github buttons to use a newer linked image & change the link
+ to their docs. Thanks to Tomi Hukkalainen.
+* #45 (via #46) Tweak styling of nested bullet lists to prevent an issue where
+ they all collapse to the same indent level when viewed on smaller display
+ sizes. Thanks to Bram Geron for catch & patch, and to Jochen Kupperschmidt
+ for review/discussion.
+* #44 (partial; via #57) Add an opt-in fixed sidebar behavior for users who
+ prefer a sidebar that never scrolls out of view. Credit: Joe Cross.
+* #61: Set a small-but-nonzero footnote width to work around a common browser
+ display bug. Thanks to Konstantin Molchanov for catch & patch.
+* #64: Add config options for font size and caption font size/family. Credit:
+ Marçal Solà.
+* #78: Add custom stylesheet support. (This release will thus be the last to
+ merge simplistic style tweaks as feature toggles - only thorny CSS issues or
+ actual template-related changes will be merged afterwards.)
+* #65: Wrap the sidebar's "Navigation" header in Sphinx's translation helper so
+ it gets translated if possible. Thanks to ``@uralbash``.
+* #77: Fix image link styling to remove a bottom border which appears in some
+ situations. Thanks to Eric Holscher for the patch & ``@barbara-sfx`` for the
+ report.
+* :release:`0.7.7 <2015-12-21>`
+* Add some ``margin-bottom`` to ``table.field-list p`` so field lists (e.g.
+ Python function parameter lists in docstrings) written as multiple
+ paragraphs, look like actual paragraphs instead of all globbing together.
+* Fix incorrect notes in README re: renamed ``github_button_*`` options - the
+ ``button_`` was dropped but docs did not reflect this. Thanks to Nik Nyby.
+* Fix ``sidebar_hr`` setting - stylesheet wasn't correctly referencing the
+ right variable name. Thanks to Jannis Leidel.
+* Allow configuring body text-align via ``body_text_align``. Credit to Marçal
+ Solà.
+* Fix a handful of mismatched/unclosed HTML tags in the templates. Thanks to
+ Marvin Pinto for catch & patch.
+* Add `Codecov <https://codecov.io>`_ badge support to sidebar.
+* :release:`0.7.6 <2015-06-22>`
+* Update how ``setup.py`` handles the ``README.rst`` file - load it explicitly
+ as UTF-8 so the changelog containing non-ASCII characters doesn't generate
+ ``UnicodeDecodeError`` in terminal environments whose default encoding is not
+ UTF-8 or other Unicode-compatible encodings. Thanks to Arun Persaud for the
+ report and Max Tepkeev for the suggested fix.
+* Fix left-margin & padding styling for code blocks within list-item elements,
+ making them consistent with earlier changes applied to top-level code blocks.
+* Expose page & sidebar widths as theme options ``page_width`` and
+ ``sidebar_width``. Their defaults are the same as the previously static
+ values.
+* :release:`0.7.5 <2015-06-15>`
+* Honor Sphinx's core ``html_show_copyright`` option when rendering page
+ footer. Thanks to Marcin Wojdyr for the report.
+* Pre-history versions of Alabaster attempted to remove the "related"
+ sub-navigation (typically found as next/previous links in other themes) but
+ this didn't work right for mobile-oriented styling.
+
+ This has been fixed by (re-)adding an improved sidebar nav element for these
+ links and making its display controllable via the new ``show_related`` theme
+ option (which defaults to ``false`` for backwards compatibility).
+
+ .. note::
+ To enable the related-links nav, you'll need to set ``show_related`` to
+ ``true`` **and** add ``relations.html`` to your ``html_sidebars`` (we've
+ updated the example config in this README to indicate this for new
+ installs).
+
+ Thanks to Tomi Pieviläinen for the bug report.
+* Update the "Fork me on Github" banner image to use an ``https://`` URI so
+ sites hosted over HTTPS don't encounter mixed-content errors. Thanks to
+ ``@nikolas`` for the patch.
+* Remove an orphaned ``</li>`` from the footer 'show source' section. Credit to
+ Marcin Wojdyr.
+* :release:`0.7.4 <2015-05-03>`
+* Add ``code_highlight`` option (which includes general fixes to styling of
+ code blocks containing highlighted lines). Thanks to Steven Loria.
+* :release:`0.7.3 <2015-03-20>`
+* Hide ``shadow`` related styles on bibliography elements, in addition to the
+ earlier change re: ``border``. Thanks again to Philippe Dessus.
+* :release:`0.7.2 <2015-03-10>`
+* Updated CSS stylesheets to apply monospace styling to both ``tt`` and
+ ``code`` elements, instead of just to ``tt``. This addresses a change in HTML
+ generation in Sphinx 1.3 while retaining support for Sphinx 1.2. Thanks to
+ Eric Holscher for the heads up.
+* :release:`0.7.1 <2015-02-27>`
+* Finally add a changelog. To the README, for now, because a full doc site
+ isn't worthwhile just yet.
+* Allow configuring a custom Github banner image (instead of simply toggling a
+ default on or off). Thanks to Nicola Iarocci for the original patch.
+* Explicitly note Python version support in the README and ``setup.py``.
+* Update Github button image link to use the newly-available HTTPS version of
+ the URL; this helps prevent errors on doc pages served via HTTPS. Thanks to
+ Gustavo Narea for the report.
+* Add control over the font size & family of code blocks. Credit to Steven
+ Loria.
+* Allow control over font family of body text and headings. Thanks to Georg
+ Brandl.
+* Stylize ``.. seealso::`` blocks same as ``.. note::`` blocks for
+ consistency's sake (previously, ``.. seealso::`` used the Sphinx default
+ styling, which clashed). We may update these again later but for now, this is
+ an improvement! Thanks again to Steven Loria.
+* Allow control over CSS ``font-style`` for the site description/tagline
+ element. Credit: Steven Loria.
+* Add styling to disable default cell borders on ``.. bibliography::``
+ directives' output. Thanks to Philippe Dessus for the report.
+* :release:`0.6.2 <2014-11-25>`
+* Make ``.. warn::`` blocks have a pink background (instead of having no
+ background, which was apparently an oversight of the themes Alabaster is
+ based on) and also make that color configurable.
+* :release:`0.6.1 <2014-09-04>`
+* Update Gittip support to acknowledge the service's rename to Gratipay.
+* :release:`0.6.0 <2014-04-17>`
+* Allow hiding the 'powered by' section of the footer.
+* Fix outdated name in ``setup.py`` URL field.
+* :release:`0.5.1 <2014-04-15>`
+* Fix a bug in the new Travis support, re: its default value.
+* :release:`0.5.0 <2014-04-09>`
+* Add support for sidebar Travis status buttons.
+* :release:`0.4.1 <2014-04-06>`
+* Fix an inaccuracy in the description of ``logo_text_align``.
+* Update logo & text styling to be more sensible.
+* :release:`0.4.0 <2014-04-06>`
+* Add an option to allow un-hiding one's toctree.
+* :release:`0.3.1 <2014-03-13>`
+* Improved Python 3 compatibility.
+* Update styling of changelog pages generated by `bitprophet/releases
+ <https://github.com/bitprophet/releases>`_.
+* :release:`0.3.0 <2014-02-03>`
+* Display Alabaster version in footers alongside Sphinx version (necessitating
+ use of a mini Sphinx extension) plus other footer tweaks.
+* :release:`0.2.0 <2014-01-28>`
+* Allow control of logo replacement text's alignment.
+* Add customized navigation sidebar element.
+* Tweak page margins a bit.
+* Add a 3rd level of medium-gray to the stylesheet & apply in a few places.
+* :release:`0.1.0 <2013-12-31>`
+* First tagged/PyPI'd version.
--- /dev/null
+from datetime import datetime
+
+
+extensions = []
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = u'Alabaster'
+year = datetime.now().year
+copyright = u'%d Jeff Forcier' % year
+
+exclude_patterns = ['_build']
+
+html_theme = 'alabaster'
+html_sidebars = {
+ '**': [
+ 'about.html',
+ 'navigation.html',
+ 'relations.html',
+ 'searchbox.html',
+ 'donate.html',
+ ]
+}
+html_theme_options = {
+ 'description': "A light, configurable Sphinx theme",
+ 'github_user': 'bitprophet',
+ 'github_repo': 'alabaster',
+ 'fixed_sidebar': True,
+}
+
+extensions.append('releases')
+releases_github_path = 'bitprophet/alabaster'
+# Our pre-0.x releases are unstable / mix bugs+features
+releases_unstable_prehistory = True
--- /dev/null
+=============
+Customization
+=============
+
+Alabaster's behavior & style can be customized in multiple ways:
+
+* Various template-level or nontrivial-style settings can be configured via
+ your ``conf.py`` in ``html_theme_options``; see :ref:`theme-options`.
+* As of Alabaster 0.7.8, you can provide your own CSS stylesheet overrides via
+ a :ref:`custom stylesheet <custom-stylesheet>`. This is suitable for changes
+ that only need minor CSS modifications.
+
+ .. note::
+ Some theme options implemented prior to 0.7.8 would have been more suitable
+ as local custom stylesheet overrides. Therefore:
+
+ * We no longer accept feature requests which are more appropriately solved
+ by using this functionality instead.
+ * In future backwards-incompatible versions we may deprecate some of those
+ options; as such we highly recommend leveraging the custom stylesheet
+ whenever possible, even if an option is present below.
+
+ * When in doubt, simply check `the built-in stylesheet's template
+ <https://github.com/bitprophet/alabaster/blob/master/alabaster/static/alabaster.css_t>`_
+ to see whether the option you're looking at is a basic variable
+ insertion or something more complicated.)
+
+
+.. _custom-stylesheet:
+
+Custom stylesheet
+=================
+
+If you need to modify Alabaster's default CSS styles in a way not covered by
+the theme options from the next section, you may provide a custom CSS
+stylesheet as follows:
+
+* Create a file named ``custom.css`` anywhere you prefer (typically
+ ``_static/``, but this is solely convention) containing your desired
+ overrides to the CSS found in Alabaster's ``static/alabaster_css_t``.
+* Set the core Sphinx option `html_static_path
+ <http://www.sphinx-doc.org/en/stable/config.html#confval-html_static_path>`_
+ to either that file's path, or the directory it lives within.
+
+
+.. _theme-options:
+
+Theme options
+=============
+
+Alabaster's primary configuration route is the ``html_theme_options`` variable,
+set in ``conf.py`` alongside the rest, e.g.:
+
+.. code-block:: python
+
+ html_theme_options = {
+ 'logo': 'logo.png',
+ 'github_user': 'bitprophet',
+ 'github_repo': 'alabaster',
+ }
+
+The following subsections detail available such options, including notes about
+behavior & default values.
+
+Variables and feature toggles
+-----------------------------
+
+* ``logo``: Relative path (from ``$PROJECT/_static/``) to a logo image, which
+ will appear in the upper left corner above the name of the project.
+
+ * If ``logo`` is not set, your ``project`` name setting (from the top
+ level Sphinx config) will be used in a text header instead. This
+ preserves a link back to your homepage from inner doc pages.
+
+* ``logo_name``: Set to ``true`` to insert your site's ``project`` name
+ under the logo image as text. Useful if your logo doesn't include the
+ project name itself. Defaults to ``false``.
+* ``logo_text_align``: Which CSS ``text-align`` value to use for logo text
+ (if there is any.)
+* ``body_text_align``: Which CSS ``text-align`` value to use for body text
+ (if there is any.)
+* ``description``: Text blurb about your project, to appear under the logo.
+* ``description_font_style``: Which CSS ``font-style`` to use for description
+ text. Defaults to ``normal``.
+* ``github_user``, ``github_repo``: Used by ``github_button`` and
+ ``github_banner`` (see below); does nothing if both of those are set to
+ ``false``.
+* ``github_button``: ``true`` or ``false`` (default: ``true``) - whether to
+ link to your Github.
+
+ * If ``true``, requires that you set ``github_user`` and ``github_repo``.
+ * See also these other related options, which behave as described in
+ `Github Buttons' documentation
+ <https://ghbtns.com>`_:
+
+ * ``github_type``: Defaults to ``watch``.
+ * ``github_count``: Defaults to ``true``.
+
+* ``github_banner``: ``true`` or ``false`` (default: ``false``) - whether to
+ apply a 'Fork me on Github' banner in the top right corner of the page.
+
+ * If ``true``, requires that you set ``github_user`` and ``github_repo``.
+ * May also submit a string file path (as with ``logo``, relative to
+ ``$PROJECT/_static/``) to be used as the banner image instead of the
+ default.
+
+* ``badge_branch``: Set which branch is used in Travis, CodeCov, etc badges.
+ Defaults to ``master``.
+
+* ``travis_button``: ``true``, ``false`` or a Github-style ``"account/repo"``
+ string - used to display a `Travis-CI <https://travis-ci.org>`_ build status
+ button in the sidebar. If ``true``, uses your ``github_(user|repo)``
+ settings; defaults to ``false.``
+* ``codecov_button``: ``true``, ``false`` or a Github-style ``"account/repo"``
+ string - used to display a `Codecov <https://codecov.io>`_ build status
+ button in the sidebar. If ``true``, uses your ``github_(user|repo)``
+ settings; defaults to ``false.``
+* ``gratipay_user``: Set to your `Gratipay <https://gratipay.com>`_ username
+ if you want a Gratipay 'Donate' section in your sidebar.
+
+ * This used to be ``gittip_user`` before that service changed its name to
+ Gratipay; we've left the old setting in place as an alias for backwards
+ compatibility reasons. It may be removed in the future.
+ * If both options are given, ``gratipay_user`` wins.
+
+* ``analytics_id``: Set to your `Google Analytics
+ <http://www.google.com/analytics/>`_ ID (e.g. ``UA-#######-##``) to enable
+ tracking.
+* ``touch_icon``: Path to an image (as with ``logo``, relative to
+ ``$PROJECT/_static/``) to be used for an iOS application icon, for when
+ pages are saved to an iOS device's home screen via Safari.
+* ``canonical_url``: If set, is used as the base URL (set before the relative
+ path/pagename) for a ``<link rel="canonical">`` `canonical URL
+ <https://support.google.com/webmasters/answer/139066?rd=1>`_ header tag.
+
+ .. note:: This value must end with a trailing slash.
+
+* ``extra_nav_links``: Dictionary mapping link names to link targets; these
+ will be added in a UL below the main sidebar navigation (provided you've
+ enabled ``navigation.html`` via the ``html_sidebars`` option; see
+ :doc:`installation`.) Useful for static links outside your Sphinx doctree.
+* ``sidebar_includehidden``: Boolean determining whether the TOC sidebar
+ should include hidden Sphinx toctree elements. Defaults to ``true`` so you
+ can use ``:hidden:`` in your index page's root toctree & avoid having 2x
+ copies of your navigation on your landing page.
+* ``sidebar_collapse``: Boolean determining whether all TOC entries that
+ are not ancestors of the current page are collapsed.
+ You can read more about this in the Sphinx toctree
+ `docs <http://www.sphinx-doc.org/en/stable/templating.html#toctree>`_.
+* ``show_powered_by``: Boolean controlling display of the ``Powered by
+ Sphinx N.N.N. & Alabaster M.M.M`` section of the footer. When ``true``, is
+ displayed next to the copyright information; when ``false``, is hidden.
+* ``show_related``: Boolean controlling whether the 'next/previous/related'
+ secondary navigation elements are hidden or displayed. Defaults to ``false``
+ since on many sites these elements are superfluous.
+* ``page_width``: CSS width specifier controlling default content/page width.
+ Defaults to ``940px``.
+* ``sidebar_width``: CSS width specifier controlling default sidebar width.
+ Defaults to ``220px``.
+* ``fixed_sidebar``: Makes the sidebar 'fixed' or pinned in place, so that the
+ main body of the page scrolls but the sidebar remains visible. (Applies only
+ to desktop window sizes; the mobile view is unaffected.) Defaults to
+ ``false``.
+
+Style colors
+------------
+
+These should be fully qualified CSS color specifiers such as ``#004B6B`` or
+``#444``. The first few items in the list are "global" colors used as defaults
+for many of the others; update these to make sweeping changes to the
+colorscheme. The more granular settings can be used to override as needed.
+
+* ``gray_1``: Dark gray.
+* ``gray_2``: Light gray.
+* ``gray_3``: Medium gray.
+* ``pink_1``: Light pink.
+* ``pink_2``: Medium pink.
+* ``body_text``: Main content text.
+* ``footer_text``: Footer text (includes links.)
+* ``link``: Non-hovered body links.
+* ``link_hover``: Body links, hovered.
+* ``sidebar_header``: Sidebar headers. Defaults to ``gray_1``.
+* ``sidebar_text``: Sidebar paragraph text.
+* ``sidebar_link``: Sidebar links (there is no hover variant.) Applies to
+ both header & text links. Defaults to ``gray_1``.
+* ``sidebar_link_underscore``: Sidebar links' underline (technically a
+ bottom-border).
+* ``sidebar_search_button``: Background color of the search field's 'Go'
+ button.
+* ``sidebar_list``: Foreground color of sidebar list bullets & unlinked text.
+* ``sidebar_hr``: Color of sidebar horizontal rule dividers. Defaults to
+ ``gray_3``.
+* ``anchor``: Foreground color of section anchor links (the 'paragraph'
+ symbol that shows up when you mouseover page section headers.)
+* ``anchor_hover_fg``: Foreground color of section anchor links (as above)
+ when moused over. Defaults to ``gray_1``.
+* ``anchor_hover_bg``: Background color of above.
+* ``note_bg``: Background of ``.. note::`` blocks. Defaults to ``gray_2``.
+* ``note_border``: Border of same.
+* ``seealso_bg``: Background of ``.. seealso::`` blocks. Defaults to
+ ``gray_2``.
+* ``seealso_border``: Border of same.
+* ``warn_bg``: Background of ``.. warn::`` blocks. Defaults to ``pink_1``.
+* ``warn_border``: Border of same. Defaults to ``pink_2``.
+* ``footnote_bg``: Background of footnote blocks.
+* ``footnote_border``: Border of same. Defaults to ``gray_2``.
+* ``pre_bg``: Background of preformatted text blocks (including code
+ snippets.) Defaults to ``gray_2``.
+* ``narrow_sidebar_bg``: Background of 'sidebar' when narrow window forces
+ it to the bottom of the page.
+* ``narrow_sidebar_fg``: Text color of same.
+* ``narrow_sidebar_link``: Link color of same. Defaults to ``gray_3``.
+* ``code_highlight``: Color of highlight when using ``:emphasize-lines:`` in a code block.
+
+Fonts
+-----
+
+* ``font_family``: Font family of body text. Defaults to ``'goudy old style',
+ 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif``.
+* ``font_size``: Font size of body text. Defaults to ``17px`` (``1.0625em``).
+* ``head_font_family``: Font family of headings. Defaults to ``'Garamond',
+ 'Georgia', serif``.
+* ``code_font_size``: Font size of code block text. Defaults to ``0.9em``.
+* ``code_font_family``: Font family of code block text. Defaults to
+ ``'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono',
+ monospace``.
+* ``caption_font_size``: Font size of caption block text. Defaults to ``font-size``.
+* ``caption_font_family``: Font family of caption block text. Defaults to ``font-family``.
--- /dev/null
+=========================
+Alabaster: a Sphinx theme
+=========================
+
+.. include:: ../README.rst
+
+Features
+========
+
+* Easy ability to install/use as a Python package (tip o' the hat to `Dave &
+ Eric's sphinx_rtd_theme <https://github.com/snide/sphinx_rtd_theme>`_ for
+ showing the way);
+* Style tweaks compared to the source themes, such as better code-block
+ alignment, Github button placement, page source link moved to footer,
+ improved (optional) related-items sidebar item, and many more;
+* Many customization hooks, including toggle of various sidebar & footer
+ components; header/link/etc color control; etc;
+* Improved documentation for all customizations (pre-existing & new).
+
+
+Project background
+==================
+
+Alabaster is a modified (with permission) version of `Kenneth Reitz's
+<http://kennethreitz.org>`_ `"krTheme" Sphinx theme
+<https://github.com/kennethreitz/kr-sphinx-themes>`_ (it's the one used
+in his `Requests <http://python-requests.org>`_ project). Kenneth's
+theme was itself originally based on Armin Ronacher's `Flask
+<http://flask.pocoo.org/>`_ theme. Many thanks to both for their hard work.
+
+
+Implementation notes
+====================
+
+* `Fabric #419 <https://github.com/fabric/fabric/issues/419>`_ contains a lot of
+ general exposition & thoughts as I developed Alabaster, specifically with a
+ mind towards using it on two nearly identical 'sister' sites (single-version
+ www 'info' site & versioned API docs site).
+* Alabaster includes/requires a tiny Sphinx extension on top of the theme
+ itself; this is just so we can inject dynamic metadata (like Alabaster's own
+ version number) into template contexts. It doesn't add any additional
+ directives or the like, at least not yet.
+
+
+.. toctree::
+ :hidden:
+ :glob:
+
+ *
--- /dev/null
+============
+Installation
+============
+
+The bare minimum required to install Alabaster is as follows:
+
+* If you're on **Sphinx 1.2 or older**:
+
+ * ``pip install alabaster`` or equivalent.
+ * Add the following to your ``conf.py`` so Alabaster's theme location &
+ mini-extension are located & loaded:
+
+ .. code-block:: python
+
+ import alabaster
+
+ html_theme_path = [alabaster.get_path()]
+ extensions = ['alabaster']
+ html_theme = 'alabaster'
+
+ * If you've installed Alabaster by hand (without using ``pip``) and/or are
+ doing funky things to your PYTHONPATH, you may need to replace the
+ ``alabaster.get_path()`` call with your own explicit string, as per `the
+ Sphinx config docs
+ <http://sphinx-doc.org/config.html#confval-html_theme_path>`_.
+
+* If you have **Sphinx 1.3 or above**:
+
+ * You already have Alabaster installed as a dependency! No need to manually
+ install it or explicitly load it.
+
+ .. note::
+ If you distribute your documentation via the excellent `Read the Docs
+ <https://readthedocs.org>`_, you may need to explicitly enable
+ Alabaster (as RTD defaults to using its own theme) by adding this line
+ to your ``conf.py``::
+
+ html_theme = 'alabaster'
+
+* **Either way**, add an explicit ``html_sidebars`` setting so Alabaster's
+ customized sidebar templates are loaded:
+
+ .. code-block:: python
+
+ html_sidebars = {
+ '**': [
+ 'about.html',
+ 'navigation.html',
+ 'relations.html',
+ 'searchbox.html',
+ 'donate.html',
+ ]
+ }
+
+That's it! You now have the standard Alabaster theme set up. Read on for more
+core configuration concerns, or see :doc:`customization` for feature/style
+options.
+
+
+Sidebars
+--------
+
+Feel free to adjust ``html_sidebars`` as desired - the theme is designed
+assuming you'll always have ``about.html`` activated, but otherwise it doesn't
+care much.
+
+* See `the Sphinx docs
+ <http://sphinx-doc.org/config.html#confval-html_sidebars>`_ for details on
+ how this setting behaves.
+* Alabaster provides ``about.html`` (logo, github button + blurb),
+ ``donate.html`` (Gratipay blurb/button) and ``navigation.html`` (a more
+ flexible version of the builtin ``localtoc``/``globaltoc`` templates).
+ ``searchbox.html`` comes with Sphinx itself.
+
+
+.. _static-path:
+
+Static path for images and/or custom stylesheet
+-----------------------------------------------
+
+If you're using any of the image-related options listed on :doc:`customization`
+(``logo`` or ``touch-icon``) or a :ref:`custom stylesheet <custom-stylesheet>`,
+you'll also want to tell Sphinx where to get these files from. If so, add a
+line like this (changing the path if necessary; see `the Sphinx docs for
+'html_static_path'
+<http://sphinx-doc.org/config.html?highlight=static#confval-html_static_path>`_) to your ``conf.py``:
+
+.. code-block:: python
+
+ html_static_path = ['_static']
--- /dev/null
+[bdist_wheel]
+universal = 1
+
+[metadata]
+license_file = LICENSE
+
+[flake8]
+ignore = E124,E125,E128,E261,E301,E302,E303
+max-line-length = 79
--- /dev/null
+#!/usr/bin/env python
+
+import codecs
+from setuptools import setup
+
+# Version info -- read without importing
+_locals = {}
+with open('alabaster/_version.py') as fp:
+ exec(fp.read(), None, _locals)
+version = _locals['__version__']
+
+# README into long description
+with codecs.open('README.rst', encoding='utf-8') as f:
+ readme = f.read()
+
+setup(
+ name='alabaster',
+ version=version,
+ description='A configurable sidebar-enabled Sphinx theme',
+ long_description=readme,
+ author='Jeff Forcier',
+ author_email='jeff@bitprophet.org',
+ url='https://alabaster.readthedocs.io',
+ packages=['alabaster'],
+ include_package_data=True,
+ entry_points={
+ 'sphinx.html_themes': [
+ 'alabaster = alabaster',
+ ]
+ },
+ classifiers=[
+ 'Development Status :: 5 - Production/Stable',
+ 'Intended Audience :: Developers',
+ 'License :: OSI Approved :: BSD License',
+ 'Operating System :: OS Independent',
+ 'Programming Language :: Python',
+ 'Programming Language :: Python :: 2',
+ 'Programming Language :: Python :: 2.6',
+ 'Programming Language :: Python :: 2.7',
+ 'Programming Language :: Python :: 3',
+ 'Programming Language :: Python :: 3.2',
+ 'Programming Language :: Python :: 3.3',
+ 'Programming Language :: Python :: 3.4',
+ 'Programming Language :: Python :: 3.5',
+ 'Programming Language :: Python :: 3.6',
+ 'Programming Language :: Python :: Implementation :: CPython',
+ 'Programming Language :: Python :: Implementation :: PyPy',
+ 'Topic :: Documentation',
+ 'Topic :: Software Development :: Documentation',
+ ],
+)
--- /dev/null
+from invoke import Collection
+from invocations import docs
+from invocations.packaging import release
+
+
+ns = Collection(release, docs)
+ns.configure({
+ 'packaging': {
+ 'sign': True,
+ 'wheel': True,
+ 'changelog_file': 'docs/changelog.rst',
+ }
+})
--- /dev/null
+
+
+.. _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
+.. _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
+
--- /dev/null
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/toto.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/toto.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/toto"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/toto"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
-***********
-application
-***********
+
+Command application
+*********************
Description
===========
* Change the directory where the application is created: ::
- sat application <application> --target </my/applications/directory>
+ sat application <application> --target </my/appli/directory>
* Set a specific SALOME resources catalog (it will be used for the distribution of components on distant machines): ::
This will create a catalog by querying each machine through ssh protocol (memory, number of processor) with ssh.
+* Generate a mesa application (if mesa and llvm are parts of the application). Use this option only if you have to use salome through ssh and have problems with ssh X forwarding of OpengGL modules (like Paravis): ::
+
+ sat launcher <application> --use_mesa
+
+Some useful configuration pathes
+=================================
-Configuration
-=============
The virtual application can be configured with the virtual_app section of the configutation file.
-* APPLICATION.virtual_app
+
+* **APPLICATION.virtual_app**
* **name**: name of the launcher (to replace the default runAppli).
* **application_name**: (optional) the name of the virtual application directory.
--- /dev/null
+
+.. include:: ../../rst_prolog.rst
+
+Command clean
+****************
+
+Description
+============
+
+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
+=======
+
+* 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
+
+* 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 <property>:<value>
+
+ * **--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
+=================================
+
+No specific configuration.
-*******
-compile
-*******
+
+Command compile
+****************
Description
===========
* Clean the build and install directories before starting compilation: ::
sat compile <application> --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: ::
sat compile <application> --show
-Configuration
-=============
+Some useful configuration pathes
+=================================
+
The way to compile a product is defined in the product configuration file (pyconf).
The main options are:
-******
-config
-******
+
+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
=====
sat config <application> --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 <parameter_path>
+ # sat config --value <parameter_path>
+ sat config --value . # all the configuration
sat config --value LOCAL
sat config --value LOCAL.workdir
- sat config <application> --value <parameter_path>
- sat config SALOME-8.4.0 --value APPLICATION.workdir
- sat config SALOME-8.4.0 -n --value APPLICATION.workdir
+ # sat config <application> --value <parameter_path>
+ 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 <application> --info <product>
- sat config SALOME-8.4.0 --info KERNEL
- sat config SALOME-8.4.0 --info qt
+ # sat config <application> --info <product>
+ 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).
--- /dev/null
+
+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.
+And so does the salome launcher.
+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
+=====
+* Create the (sh) environment files of the application: ::
+
+ sat environ <application>
+
+* Create the environment files of the application for a given shell.
+ Options are bash, bat (for windows) and cfg (the configuration format used by salomé): ::
+
+ sat environ <application> --shell [bash|cfg|all]
+
+* Use a different prefix for the files (default is 'env'): ::
+
+ sat environ <application> --prefix <prefix>
+ This will create file <prefix>_launch.sh, <prefix>_build.sh...
+
+* Use a different target directory for the files: ::
+
+ sat environ <application> --target <path>
+ This will create file env_launch.sh, env_build.sh... in the directory corresponding to <path>
+
+* Generate the environment files only with the given products: ::
+
+ sat environ <application> --product <product1> --product <product2> ....
+ This will create the environment files only for the given products and their prerequisites.
+ It is useful when you want to visualise which environment uses sat to compile a given product.
+
+
+Configuration
+=============
+
+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.
+
+2. For other products, the environment is set with the use of the environ section within the pyconf file of the product. The user has two possibilities, either set directly the environment within the section, or specify a python script which wil be used to set the environment programmatically.
+
+Within the section, the user can define environment variables. He can also modify PATH variables, by appending or prepending directories.
+In the following example, we prepend <install_dir>/lib to LD_LIBRARY_PATH (note the underscore before), append <install_dir>/lib to PYTHONPATH (the underscore is after!), and set LAPACK_ROOT_DIR to <install_dir>: ::
+
+ environ :
+ {
+ _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib"
+ PYTHONPATH_ : $install_dir + $VARS.sep + "lib"
+ LAPACK_ROOT_DIR : $install_dir
+ }
+
+It is possible here to distinguish the build environment from the launch environment. For that, use a subsection called build or launch. In the example below, LD_LIBRARY_PATH and PYTHONPATH are only modified at run time, not at compile time: ::
+
+ environ :
+ {
+ build
+ {
+ LAPACK_ROOT_DIR : $install_dir
+ }
+ launch
+ {
+ LAPACK_ROOT_DIR : $install_dir
+ _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib"
+ PYTHONPATH_ : $install_dir + $VARS.sep + "lib"
+ }
+ }
+
+3. The last possibility is to set the environment with a python script. The script should be provided in the products/env_scripts directory of the sat project, and its name is specified in the environment section with the key **env_script**: ::
+
+ environ :
+ {
+ env_script : "lapack.py"
+ }
+
+Please note that the two modes are complementary and are both taken into account.
+Most of the time, the first mode is sufficient. The second mode can be used when the environment has to be set programmatically.
+Here is an example: ::
+
+ #!/usr/bin/env python
+ #-*- coding:utf-8 -*-
+
+ import os.path
+ import platform
+
+ def set_env(env, prereq_dir, version):
+ env.set("TRUST_ROOT_DIR",prereq_dir)
+ env.prepend('PATH', os.path.join(prereq_dir, 'bin'))
+ env.prepend('PATH', os.path.join(prereq_dir, 'include'))
+ env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
+ pass
+
+The developer implements a handle which is called by sat to set the environment.
+sat defines four handles:
+
+* *set_env(env, prereq_dir, version)* : used at build and run time.
+* *set_env_launch(env, prereq_dir, version)* : used only at run time (if defined!)
+* *set_env_build(env, prereq_dir, version)* : used only at build time (if defined!)
+* *set_native_env(env)* : used only for native products, at build and run time.
--- /dev/null
+****************
+Command generate
+****************
+
+Description
+===========
+The **generate** command generates and compile SALOME modules from cpp modules using YACSGEN.
+
+.. note:: This command uses YACSGEN to generate the module. It needs to be specified with *--yacsgen* option, or defined in the product or by the environment variable ``$YACSGEN_ROOT_DIR``.
+
+
+Remarks
+=======
+* This command will only apply on the CPP modules of the application, those who have both properties: ::
+
+ cpp : "yes"
+ generate : "yes"
+
+* The cpp module are usually computational components, and the generated module brings the CORBA layer which allows distributing the compononent on remore machines. cpp modules should conform to YACSGEN/hxx2salome requirements (please refer to YACSGEN documentation)
+
+
+Usage
+=====
+* Generate all the modules of a product: ::
+
+ sat generate <application>
+
+* Generate only specific modules: ::
+
+ sat generate <application> --products <list of products>
+
+ Remark: modules which don't have the *generate* property are ignored.
+
+* Use a specific version of YACSGEN: ::
+
+ sat generate <application> --yacsgen <path to yacsgen>
+
-********
-launcher
-********
+
+Command launcher
+******************
Description
===========
Generate a launcher in the application directory, i.e ``$APPLICATION.workdir``.
-* Create a launcher with a given name ::
+* Create a launcher with a given name (default name is APPLICATION.profile.launcher_name) ::
- sat launcher <application>
+ sat launcher <application> --name ZeLauncher
The launcher will called ZeLauncher.
* Set a specific resources catalog: ::
- sat launcher <application>
+ sat launcher <application> --catalog <path of a salome resources catalog>
Note that the catalog specified will be copied to the profile directory.
* Generate the catalog for a list of machines: ::
- sat launcher <application>
+ sat launcher <application> --gencat <list of machines>
This will create a catalog by querying each machine (memory, number of processor) with ssh.
+* Generate a mesa launcher (if mesa and llvm are parts of the application). Use this option only if you have to use salome through ssh and have problems with ssh X forwarding of OpengGL modules (like Paravis): ::
+
+ sat launcher <application> --use_mesa
+
+
Configuration
=============
-* APPLICATION.profile
+
+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)
* **launcher_name**: the name of the launcher.
-***
-log
-***
+
+
+Command log
+****************
Description
===========
-Configuration
-=============
+Some useful configuration pathes
+=================================
+
* USER.browser
* **browser**: The browser used to show the log (by default *firefox*).
--- /dev/null
+
+.. 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 archive includes sources and binaries
+of SALOME products and prerequisites.
+
+Usually utility *salomeTools* is included in the archive.
+
+.. note::
+ By default the package includes the sources of prerequisites and products.
+ To select a subset use the *--without_property* or *--with_vcs* options.
+
+
+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 (prerequisites and products) are
+ included in the package, the OS_ architecture
+ will be appended to the name (example: *SALOME_xx-CO7.tgz*).
+
+ Examples: ::
+
+ # Creates SALOME_xx.tgz in $USER.workDir
+ sat package SALOME_xx
+
+ # Creates SALOME_xx_<arch>.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 _<arch>.tgz``
+ where <arch> is the OS_ architecture of the machine.
+
+
+* Do not delete Version Control System (VCS_) informations from the configurations files of the embedded salomeTools: ::
+
+ sat package <product> --with_vcs
+
+ The version control systems known by this option are CVS_, SVN_ and Git_.
+
+
+Some useful configuration pathes
+=================================
+
+No specific configuration.
-*******
-prepare
-*******
+
+Command prepare
+****************
Description
===========
-The **prepare** command brings the sources of an application in the SOURCES application directory, in order to compile them with the compile command.
+The **prepare** command brings the sources of an application in the SOURCES
+application directory, in order to compile them with the compile command.
The sources can be prepared from VCS software (*cvs*,*svn*, *git*), an archive or a directory.
-.. warning:: When sat prepares a product, it first removes the existing directory, except if the developement mode is activated.
- When you are working on a product,, you need to declare in the application configuration this product in **dev** mode.
+.. warning:: When sat prepares a product, it first removes the
+ existing directory, except if the development mode is activated.
+ When you are working on a product, you need to declare in
+ the application configuration this product in **dev** mode.
Remarks
=======
The *prepare* command does not manage authentication on the cvs server.
For example, to prepare modules from a cvs server, you first need to login once.
-To avoid typing a password for each product, you may use a ssh key with passphrase, or store your password (in .cvspass or .gitconfig).
-If you have security concerns, it is also possible to use a bash agent and type your password only once.
+To avoid typing a password for each product,
+you may use a ssh key with passphrase, or store your password
+(in .cvspass or .gitconfig).
+If you have security concerns, it is also possible to use
+a bash agent and type your password only once.
Dev mode
--------
-By default *prepare* uses *export* mode: it creates an image of the sources, corresponding to the tag or branch specified, without any link to the VCS base.
-To perform a *checkout* (svn, cvs) or a *git clone* (git), you need to declare the product in dev mode in your application configuration.
+By default *prepare* uses *export* mode: it creates an image
+of the sources, corresponding to the tag or branch specified,
+without any link to the VCS base.
+To perform a *checkout* (svn, cvs) or a *git clone* (git),
+you need to declare the product in dev mode in your application configuration.
For that, edit the application configuration and modify the product declaration: ::
sat config <application> -e
# edit the product section :
-
<product> : {tag : "my_tag", dev : "yes", debug : "yes"}
+
# <product> : {tag : "my_tag", dev : "yes", debug : "yes"}
-The first time you will execute the *sat prepare* command, your module will be downloaded in *checkout* mode (inside the SOURCES directory of the application.
-Then, you can develop in this repository. And push them in the base when they are ready.
-If you type during the development process by mistake a *sat prepare* command, the sources in dev mode will not be altered/removed (Unless you use -f option)
+The first time you will execute the *sat prepare* command,
+your module will be downloaded in *checkout* mode
+(inside the SOURCES directory of the application.
+Then, you can develop in this repository, and finally push
+them in the base when they are ready.
+If you type during the development process by mistake
+a *sat prepare* command, the sources in dev mode will
+not be altered/removed (Unless you use -f option)
Usage
sat prepare <application> --products <product1>,<product2> ...
-* Use --force to force to prepare the products in development mode (this will remove the sources and do a new clone/checkout): ::
+* Use --force to force to prepare the products in development mode
+ (this will remove the sources and do a new clone/checkout): ::
sat prepare <application> --force
-* Use --force_patch to force to apply patch to the products in development mode (otherwise they are not applied): ::
+* Use --force_patch to force to apply patch to the products
+ in development mode (otherwise they are not applied): ::
sat prepare <application> --force_patch
-Configuration
-=============
-* sat prepare uses the pyconf configuration of each product to know how to get the sources.
+Some useful configuration pathes
+=================================
+
+Command *sat prepare* uses the file 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.
- * **git_info**: (used if get_method = git) information to prepare sources from git.
- * **svn_info**: (used if get_method = svn) information to prepare sources from cvs.
- * **cvs_info**: (used if get_method = cvs) information to prepare sources from cvs.
- * **archive_info**: (used if get_method = archive) the path to the archive.
- * **dir_info**: (used if get_method = dir) the directory with the sources.
+* **get_method**: the method to use to prepare the module, possible values are cvs, git, archive, dir.
+* **git_info**: (used if get_method = git) information to prepare sources from git.
+* **svn_info**: (used if get_method = svn) information to prepare sources from cvs.
+* **cvs_info**: (used if get_method = cvs) information to prepare sources from cvs.
+* **archive_info**: (used if get_method = archive) the path to the archive.
+* **dir_info**: (used if get_method = dir) the directory with the sources.
# -*- coding: utf-8 -*-
#
-# salomeTools documentation build configuration file, created by
-# sphinx-quickstart on Wed Sep 14 11:55:14 2011.
+# sat documentation build configuration file, created by
+# sphinx-quickstart on Fri Apr 13 10:08:59 2018.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
+
+# 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.
templates_path = ['_templates']
# General information about the project.
project = u'salomeTools'
-copyright = u'2010-2016, CEA'
+copyright = u'2018, CEA'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# default sphinxdoc scrolls agogo traditional nature haiku
-html_theme = 'default'
+html_theme = 'alabaster' #added in _theme dir
# 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
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ #'logo': 'logo.png',
+ #'github_user': 'bitprophet',
+ #'github_repo': 'alabaster',
+ #'description': 'MYYY DESCRIPTION',
+ #'sidebar_includehidden': True,
+ #'sidebar_collapse': True,
+ #'show_powered_by': False,
+ 'show_related': True,
+ 'fixed_sidebar': False,
+ 'page_width': '1000px',
+ 'sidebar_width': '250px',
+ 'font_size': '0.9em', #'1.0625em',
+ 'code_font_size': '0.8em',
+ #'note_bg': '#eee',
+ 'pre_bg': '#fee', # code-block background
+ #'gray_1': '#00f',
+ #'gray_2': '#f00',
+ #'gray_3': '#0f0',
+}
# 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
# "<project> v<release> documentation".
# 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/salomeTools.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,
# -- Options for LaTeX output --------------------------------------------------
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ 'papersize': 'a4paper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ #'preamble': '',
+}
+
+
# The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
+#latex_paper_size = 'a4'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'salomeTools.tex', u'salomeTools Documentation',
- u'CEA', 'manual'),
+ u'CEA DEN/DANS/DM2S/STMF/LGLS', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
-#latex_show_urls = False
+latex_show_urls = True
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'salometools', u'salomeTools Documentation',
- [u'CEA'], 1)
+ [u'CEA DEN/DANS/DM2S/STMF/LGLS'], 1)
]
# Append source folder to path in order to enable autodoc
-sys.path.append(os.path.join('..'))
\ No newline at end of file
+currentPath = os.path.dirname(__file__)
+print "file conf.py currentPath", currentPath
+sys.path.append(os.path.join(currentPath, '..', '..'))
--- /dev/null
+*************
+Configuration
+*************
+
+*salomeTools* uses files to store its configuration parameters.
+
+There are several configuration files which are loaded by salomeTools in a specific order.
+When all the files are loaded a *config* object is created.
+Then, this object is passed to all command scripts.
+
+
+Syntax
+======
+The configuration files use a python-like structure format
+(see `config module <http://www.red-dove.com/config-doc/>`_ for a complete description).
+
+* **{}** define a dictionary,
+* **[]** define a list,
+* **@** can be used to include a file,
+* **$prefix** reference to another parameter (ex: ``$PRODUCT.name``),
+* **#** comments.
+
+.. note:: in this documentation a reference to a configuration parameter will be noted ``$XXX.YYY``.
+
+Description
+===========
+
+.. _VARS-Section:
+
+VARS section
+-------------
+| This section is dynamically created by salomeTools at run time.
+| It contains information about the environment: date, time, OS, architecture etc.
+
+.. note:: use this command to get the current setting: *sat config -v VARS*
+
+
+PRODUCTS section
+------------------
+| This section is defined in the product file.
+| It contains instructions on how to build a version of SALOME (list of prerequisites-products and versions)
+
+.. note:: use this command to get the current setting: *sat config SALOME-xx -v PRODUCTS*
+
+APPLICATION section
+---------------------
+| This section is optional, it is also defined in the product file.
+| It gives additional parameters to create an application based on SALOME, as versions of products to use.
+
+.. note:: use this command to get the current setting: *sat config SALOME-xx -v APPLICATION*
+
+.. _USER-Section:
+
+USER section
+--------------
+This section is defined by the user configuration file
+which is located in *~/.salomeTools/salomeTools.pyconf*.
+
+The USER section defines parameters (not exhaustive):
+
+* **workDir** the working directory. Each product will be usually installed here (in sub-directories).
+* and other users preferences.
+
+.. note:: use this command to get the current setting: *sat config SALOME-xx -v USER*.
+
+
+
+
+
+.. include:: ../rst_prolog.rst
+
************
-SAlome Tools
+Salome Tools
************
-.. note::
-
- This documentation is under construction.
+.. 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
+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.
-SAlomeTools (sat) is a suite of commands that can be used to perform operations on SALOME.
+This utility code is a set of Python_ scripts files.
-For example, sat allows you to compile SALOME's modules or prerequisites, create an application, run tests, create a package...
Quick start
===========
.. toctree::
:maxdepth: 1
- Installation of salomeTools (to be competed)
- Configuration (to be competed)
- Usage of salomeTools (to be competed)
+ Installation of salomeTools <installation_of_sat>
+ Configuration <configuration>
+ Usage of salomeTools <usage_of_sat>
List of Commands
================
launcher <commands/launcher>
application <commands/application>
log <commands/log>
+ environ <commands/environ>
+ clean <commands/clean>
+ package <commands/package>
+ generate <commands/generate>
-Code documentation
-==================
+Developer documentation
+=======================
.. toctree::
:maxdepth: 1
- SAT modules <commands/apidoc/modules.rst>
+ Add a command <write_command>
-developer documentation
-=======================
+
+Code documentation
+==================
.. toctree::
:maxdepth: 1
- Add a command <write_command>
+ SAT modules <commands/apidoc/modules.rst>
+
Release Notes
=============
-Here are the release notes for sat:
.. toctree::
:maxdepth: 1
- Release Notes 5.0.0 (to be completed)
+ Release Notes 5.0.0 <release_notes/release_notes_5.0.0>
--- /dev/null
+************
+Installation
+************
+
+Usually user could find (and use) command **sat** directly after a 'detar' installation of SALOME.
+
+.. code-block:: bash
+
+ tar -xf .../SALOME_xx.tgz
+ cd SALOME_xx
+ ls -l sat # sat -> salomeTools/sat
+
+
+Python package (scripts of salomeTools) actually remains in directory *salomeTools*.
+
--- /dev/null
+***************
+Release notes
+***************
+
+In construction.
--- /dev/null
+
+.. include:: ../rst_prolog.rst
+
+********************
+Usage of SAlomeTools
+********************
+
+Usage
+=====
+sat usage is a Command Line Interface (CLI_).
+
+.. code-block:: bash
+
+ sat [generic_options] [command] [product] [command_options]
+
+Options of sat
+--------------
+
+Useful *not exhaustive* generic options of *sat* CLI.
+
+*--help or -h*
+...............
+
+Get help as simple text.
+
+.. code-block:: bash
+
+ sat --help # get the list of existing commands
+ sat --help compile # get the help on a specific command 'compile'
+
+
+*--debug or -g*
+................
+
+Execution in debug mode allows to see more trace and *stack* if an exception is raised.
+
+*--verbose or -v*
+..................
+
+Change verbosity level (default is 3).
+
+.. code-block:: bash
+
+ # for product 'SALOME_xx' for example
+ # execute compile command in debug mode with trace level 4
+ sat -g -v 4 compile SALOME_xx
+
+
+Build a SALOME product
+======================
+
+Get the list of available products
+----------------------------------
+
+To get the list of the current available products in your context:
+
+.. code-block:: bash
+
+ sat config --list
+
+Prepare sources of a product
+----------------------------
+
+To prepare (get) *all* the sources of a product (*SALOME_xx* for example):
+
+.. code-block:: bash
+
+ sat prepare SALOME_xx
+
+| The sources are usually copied in directories
+| *$USER.workDir + SALOME_xx... + SOURCES + $PRODUCT.name*
+
+
+Compile SALOME
+----------------
+
+To compile products:
+
+.. code-block:: bash
+
+ # compile all prerequisites/products
+ sat compile SALOME_xx
+
+ # compile only 2 products (KERNEL and SAMPLES), if not done yet
+ sat compile SALOME_xx --products KERNEL,SAMPLES
+
+ # compile only 2 products, unconditionaly
+ sat compile SALOME_xx ---products SAMPLES --clean_all
+
+
+| The products are usually build in the directories
+| *$USER.workDir + SALOME_xx... + BUILD + $PRODUCT.name*
+|
+| The products are usually installed in the directories
+| *$USER.workDir + SALOME_xx... + INSTALL + $PRODUCT.name*
+
+
-***************
-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.
(options, args) = parser.parse_args(args)
# algorithm
-How to access to salomeTools config and other commands ?
+HowTo access salomeTools config and other commands
========================================================
-The runner variable is an instance of the Sat class. It gives access to cfg : the data model that is read from all configuration files of salomeTools (*.pyconf) For example, runner.cfg.APPLICATION.out_dir will contain the root directory of the application on which you are working.
+The *runner* variable is an python instance of *Sat* class.
+It gives access to *runner.cfg* : the data model that is read from all
+configuration files of salomeTools (*.pyconf)
+For example, *runner.cfg.APPLICATION.workdir* will
+contain the root directory of the application on which you are working.
-It gives also access to all other commands of salomeTools :
+The *runner* variable gives also access to other commands of salomeTools:
.. code-block:: python
runner.prepare(runner.cfg.VARS.application)
-How to log ?
-============
+HowTo logger
+==============
-The logger variable is an instance of the Logger class. It gives access to the write method.
+The logger variable is an instance of the Logger class.
+It gives access to the write method.
-When this method is called, the message passed as parameter will be displayed in the termnial and written in an xml log file.
+When this method is called, the message passed as parameter
+will be displayed in the terminal and written in an xml log file.
.. code-block:: python
logger.write("My message", 3)
-The second argument defines the level of verbosity that is wanted for this message. It has to be between 1 and 5 (the most verbose level).
+The second argument defines the level of verbosity
+that is wanted for this message.
+It has to be between 1 and 5 (the most verbose level).
-HELLO WORLD !
-=============
+HELLO example
+==============
-Here is a hello world command :
+Here is a 'hello' command, file *commands/hello.py*:
.. code-block:: python
import src
- # Define all possible option for mycommand command : sat mycommand <options>
+ """
+ hello.py
+ Define all possible options for hello command:
+ sat hello <options>
+ """
parser = src.options.Options()
- parser.add_option('m', 'myoption', 'boolean', 'myoption', "My option changes the behavior of my command.")
+ parser.add_option('f', 'french', 'boolean', 'french', "french set hello message in french.")
def description():
- return _("The help of mycommand.")
+ return _("The help of hello.")
def run(args, runner, logger):
# Parse the options
(options, args) = parser.parse_args(args)
# algorithm
- if options.myoption:
- logger.write('HELLO, WORLD !\n')
+ if not options.french:
+ logger.write('HELLO! WORLD!\n')
else:
- logger.write('WORLD, HELLO !\n')
+ logger.write('Bonjour tout le monde!\n')
-A first call of mycommand:
+A first call of hello:
.. code-block:: bash
- >./sat mycommand --myoption
- HELLO, WORLD !
+ # Get the help of hello:
+ ./sat --help hello
- Tap the following command to get the log :
- /path/to/salomeTools/sat log
-
-Another call of mycommand:
+ # To get bonjour
+ ./sat hello -f
+ Bonjour tout le monde!
+
+ # To get hello
+ ./sat hello
+ HELLO! WORLD!
-.. code-block:: bash
+ # To get the log
+ ./sat log
- >./sat mycommand
- WORLD, HELLO !
- Tap the following command to get the log :
- /path/to/salomeTools/sat log
-
-Get the help of mycommand:
-.. code-block:: bash
-
- >./sat --help mycommand
- Version: 5.0.0dev
-
- Description:
- The help of mycommand.
+
- Available options are:
- -m, --myoption (boolean)
- My option changes the behavior of my command.
\ No newline at end of file
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+"""\
+initial imports and utilities methods for salomeTools
+"""
+
import os
import shutil
import errno
CONFIG_FILENAME = "sat-config.pyconf"
class SatException(Exception):
- '''rename Exception Class
- '''
+ """rename Exception Class"""
pass
def ensure_path_exists(p):
- '''Create a path if not existing
+ """Create a path if not existing
:param p str: The path.
- '''
+ """
if not os.path.exists(p):
os.makedirs(p)
def check_config_has_application( config, details = None ):
- '''check that the config has the key APPLICATION. Else raise an exception.
+ """check that the config has the key APPLICATION. Else raise an exception.
:param config class 'common.pyconf.Config': The config.
- '''
+ """
if 'APPLICATION' not in config:
message = _("An APPLICATION is required. Use 'config --list' to get"
" the list of available applications.\n")
raise SatException( message )
def check_config_has_profile( config, details = None ):
- '''check that the config has the key APPLICATION.profile.
- Else, raise an exception.
+ """\
+ check that the config has the key APPLICATION.profile.
+ else, raise an exception.
:param config class 'common.pyconf.Config': The config.
- '''
+ """
check_config_has_application(config)
if 'profile' not in config.APPLICATION:
message = _("A profile section is required in your application.\n")
return 'APPLICATION' in config
def get_cfg_param(config, param_name, default):
- '''Search for param_name value in config.
- If param_name is not in config, then return default,
- else, return the found value
+ """\
+ eearch for param_name value in config.
+ if param_name is not in config
+ then return default,
+ else return the found value
:param config class 'common.pyconf.Config': The config.
:param param_name str: the name of the parameter to get the value
:param default str: The value to return if param_name is not in config
:return: see initial description of the function
:rtype: str
- '''
+ """
if param_name in config:
return config[param_name]
return default
def print_info(logger, info):
- '''Prints the tuples that are in info variable in a formatted way.
+ """\
+ Prints the tuples that are in info variable in a formatted way.
:param logger Logger: The logging instance to use for the prints.
:param info list: The list of tuples to display
- '''
+ """
# find the maximum length of the first value of the tuples in info
smax = max(map(lambda l: len(l[0]), info))
# Print each item of info with good indentation
logger.write("\n", 2)
def get_base_path(config):
- '''Returns the path of the products base.
+ """\
+ Returns the path of the products base.
:param config Config: The global Config instance.
:return: The path of the products base.
:rtype: str
- '''
+ """
if "base" not in config.LOCAL:
local_file_path = os.path.join(config.VARS.salometoolsway,
"data",
return base_path
def get_launcher_name(config):
- '''Returns the name of salome launcher.
+ """\
+ Returns the name of salome launcher.
:param config Config: The global Config instance.
:return: The name of salome launcher.
:rtype: str
- '''
+ """
check_config_has_application(config)
if 'profile' in config.APPLICATION and 'launcher_name' in config.APPLICATION.profile:
launcher_name = config.APPLICATION.profile.launcher_name
return launcher_name
def get_log_path(config):
- '''Returns the path of the logs.
+ """\
+ Returns the path of the logs.
:param config Config: The global Config instance.
:return: The path of the logs.
:rtype: str
- '''
+ """
if "log_dir" not in config.LOCAL:
local_file_path = os.path.join(config.VARS.salometoolsway,
"data",
return False
def find_file_in_lpath(file_name, lpath, additional_dir = ""):
- """Find in all the directories in lpath list the file that has the same name
- as file_name. If it is found, return the full path of the file, else,
- return False.
- The additional_dir (optional) is the name of the directory to add to all
- paths in lpath.
+ """\
+ Find in all the directories in lpath list the file that has the same name
+ as file_name.
+ If it is found
+ then return the full path of the file
+ else return False.
+
+ The additional_dir (optional) is the name of the directory to add to all
+ paths in lpath.
:param file_name str: The file name to search
:param lpath List: The list of directories where to search
raise
def deepcopy_list(input_list):
- """ Do a deep copy of a list
+ """\
+ Do a deep copy of a list
:param input_list List: The list to copy
:return: The copy of the list
return res
def remove_item_from_list(input_list, item):
- """ Remove all occurences of item from input_list
+ """\
+ Remove all occurences of item from input_list
:param input_list List: The list to modify
:return: The without any item
return res
def parse_date(date):
- """Transform YYYYMMDD_hhmmss into YYYY-MM-DD hh:mm:ss.
+ """\
+ Transform YYYYMMDD_hhmmss into YYYY-MM-DD hh:mm:ss.
:param date str: The date to transform
:return: The date in the new format
return res
def merge_dicts(*dict_args):
- '''
+ """\
Given any number of dicts, shallow copy and merge into a new dict,
precedence goes to key value pairs in latter dicts.
- '''
+ """
result = {}
for dictionary in dict_args:
result.update(dictionary)
return result
def replace_in_file(filein, strin, strout):
- '''Replace <strin> by <strout> in file <filein>
- '''
+ """Replace <strin> by <strout> in file <filein>"""
shutil.move(filein, filein + "_old")
fileout= filein
filein = filein + "_old"
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""
+"""\
This file assume DEBUG functionalities use
+
- print debug messages in sys.stderr for salomeTools
- show pretty print debug representation from instances of SAT classes
(pretty print src.pyconf.Config), and python dict/list etc. (as 'aVariable')
return
def tofix(title, var="", force=None):
- """
+ """\
write sys.stderr a message if _debug[-1]==True or optionaly force=True
use this only if no logger accessible for classic
logger.warning(message) or logger.debug(message)
config.__save__(aStream, indent)
def getStrConfigStd(config):
- """set string as saveConfigStd,
- as file .pyconf"""
+ """set string as saveConfigStd, as file .pyconf"""
outStream = OutStream()
saveConfigStd(config, outStream)
return outStream.value
def getStrConfigDbg(config):
- """set string as saveConfigDbg,
- as (path expression evaluation) for debug"""
+ """\
+ set string as saveConfigDbg,
+ as (path expression evaluation) for debug
+ """
outStream = OutStream()
saveConfigDbg(config, outStream)
return outStream.value
import pprint as PP
class Environ:
- '''Class to manage the environment context
- '''
+ """\
+ Class to manage the environment context
+ """
def __init__(self, environ=None):
- '''Initialization. If the environ argument is passed, the environment
+ """Initialization. If the environ argument is passed, the environment
will be add to it, else it is the external environment.
:param environ dict:
- '''
+ """
if environ is not None:
self.environ = environ
else:
self.environ = os.environ
def __repr__(self):
- """easy non exhaustive quick resume for debug print
- """
+ """easy non exhaustive quick resume for debug print"""
return "%s(\n%s\n)" % (self.__class__.__name__, PP.pformat(self.environ))
def _expandvars(self, value):
- '''replace some $VARIABLE into its actual value in the environment
+ """\
+ replace some $VARIABLE into its actual value in the environment
:param value str: the string to be replaced
:return: the replaced variable
:rtype: str
- '''
+ """
if "$" in value:
# The string.Template class is a string class
# for supporting $-substitutions
return value
def append_value(self, key, value, sep=os.pathsep):
- '''append value to key using sep
+ """\
+ append value to key using sep
:param key str: the environment variable to append
:param value str: the value to append to key
:param sep str: the separator string
- '''
+ """
# check if the key is already in the environment
if key in self.environ:
value_list = self.environ[key].split(sep)
self.set(key, value)
def append(self, key, value, sep=os.pathsep):
- '''Same as append_value but the value argument can be a list
+ """\
+ Same as append_value but the value argument can be a list
:param key str: the environment variable to append
:param value str or list: the value(s) to append to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
for v in value:
self.append_value(key, v, sep)
self.append_value(key, value, sep)
def prepend_value(self, key, value, sep=os.pathsep):
- '''prepend value to key using sep
+ """\
+ prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
:param sep str: the separator string
- '''
+ """
if key in self.environ:
value_list = self.environ[key].split(sep)
if not value in value_list:
self.set(key, value)
def prepend(self, key, value, sep=os.pathsep):
- '''Same as prepend_value but the value argument can be a list
+ """\
+ Same as prepend_value but the value argument can be a list
:param key str: the environment variable to prepend
:param value str or list: the value(s) to prepend to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
for v in value:
self.prepend_value(key, v, sep)
self.prepend_value(key, value, sep)
def is_defined(self, key):
- '''Check if the key exists in the environment
+ """\
+ Check if the key exists in the environment
:param key str: the environment variable to check
- '''
+ """
return key in self.environ.keys()
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """\
+ Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
self.environ[key] = self._expandvars(value)
def get(self, key):
- '''Get the value of the environment variable "key"
+ """\
+ Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
if key in self.environ:
return self.environ[key]
else:
return ""
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
value = subprocess.Popen(command,
shell=True,
stdout=subprocess.PIPE,
class SalomeEnviron:
- """Class to manage the environment of SALOME.
+ """\
+ Class to manage the environment of SALOME.
"""
-
def __init__(self,
cfg,
environ,
forBuild=False,
for_package=None,
enable_simple_env_script = True):
- '''Initialization.
+ """\
+ Initialization.
:param cfg Config: the global config
:param environ Environ: the Environ instance where
else a build one
:param for_package str: If not None, produce a relative environment
designed for a package.
- '''
+ """
self.environ = environ
self.cfg = cfg
self.forBuild = forBuild
return "%s(\n%s\n)" % (self.__class__.__name__, PP.pformat(res))
def append(self, key, value, sep=os.pathsep):
- '''append value to key using sep
+ """\
+ append value to key using sep
:param key str: the environment variable to append
:param value str: the value to append to key
:param sep str: the separator string
- '''
+ """
return self.environ.append(key, value, sep)
def prepend(self, key, value, sep=os.pathsep):
- '''prepend value to key using sep
+ """\
+ prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
:param sep str: the separator string
- '''
+ """
return self.environ.prepend(key, value, sep)
def is_defined(self, key):
- '''Check if the key exists in the environment
+ """\
+ Check if the key exists in the environment
:param key str: the environment variable to check
- '''
+ """
return self.environ.is_defined(key)
def get(self, key):
- '''Get the value of the environment variable "key"
+ """\
+ Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
return self.environ.get(key)
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """\
+ Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
# check if value needs to be evaluated
if value is not None and value.startswith("`") and value.endswith("`"):
res = subprocess.Popen("echo %s" % value,
return self.environ.set(key, value)
def dump(self, out):
- """Write the environment to out
+ """\
+ Write the environment to out
:param out file: the stream where to write the environment
"""
out.write("%s=%s\n" % (k, value))
def add_line(self, nb_line):
- """Add empty lines to the out stream (in case of file generation)
+ """\
+ Add empty lines to the out stream (in case of file generation)
:param nb_line int: the number of empty lines to add
"""
self.environ.add_line(nb_line)
def add_comment(self, comment):
- """Add a commentary to the out stream (in case of file generation)
+ """\
+ Add a commentary to the out stream (in case of file generation)
:param comment str: the commentary to add
"""
self.environ.add_comment(comment)
def add_warning(self, warning):
- """Add a warning to the out stream (in case of file generation)
+ """\
+ Add a warning to the out stream (in case of file generation)
:param warning str: the warning to add
"""
self.environ.add_warning(warning)
def finish(self, required):
- """Add a final instruction in the out file (in case of file generation)
+ """\
+ Add a final instruction in the out file (in case of file generation)
:param required bool: Do nothing if required is False
"""
self.environ.finish(required)
def set_python_libdirs(self):
- """Set some generic variables for python library paths
- """
+ """Set some generic variables for python library paths"""
ver = self.get('PYTHON_VERSION')
self.set('PYTHON_LIBDIR0', os.path.join('lib',
'python' + ver,
self.python_lib1 = self.get('PYTHON_LIBDIR1')
def get_names(self, lProducts):
- """Get the products name to add in SALOME_MODULES environment variable
- It is the name of the product, except in the case where the is a
- component name. And it has to be in SALOME_MODULES variable only
- if the product has the property has_salome_hui = "yes"
+ """\
+ Get the products name to add in SALOME_MODULES environment variable
+ It is the name of the product, except in the case where the is a
+ component name. And it has to be in SALOME_MODULES variable only
+ if the product has the property has_salome_hui = "yes"
:param lProducts list: List of products to potentially add
"""
return lProdName
def set_application_env(self, logger):
- """Sets the environment defined in the APPLICATION file.
+ """\
+ Sets the environment defined in the APPLICATION file.
:param logger Logger: The logger instance to display messages
"""
self.add_line(1)
def set_salome_minimal_product_env(self, product_info, logger):
- """Sets the minimal environment for a SALOME product.
- xxx_ROOT_DIR and xxx_SRC_DIR
+ """\
+ Sets the minimal environment for a SALOME product.
+ xxx_ROOT_DIR and xxx_SRC_DIR
:param product_info Config: The product description
:param logger Logger: The logger instance to display messages
product_info.name))
def set_salome_generic_product_env(self, pi):
- """Sets the generic environment for a SALOME product.
+ """\
+ Sets the generic environment for a SALOME product.
:param pi Config: The product description
"""
self.prepend('PYTHONPATH', l)
def set_cpp_env(self, product_info):
- """Sets the generic environment for a SALOME cpp product.
+ """\
+ Sets the generic environment for a SALOME cpp product.
:param product_info Config: The product description
"""
self.prepend('PYTHONPATH', l)
def load_cfg_environment(self, cfg_env):
- """Loads environment defined in cfg_env
+ """\
+ Loads environment defined in cfg_env
:param cfg_env Config: A config containing an environment
"""
self.set(env_def, val)
def set_a_product(self, product, logger):
- """Sets the environment of a product.
+ """\
+ Sets the environment of a product.
:param product str: The product name
:param logger Logger: The logger instance to display messages
def run_env_script(self, product_info, logger=None, native=False):
- """Runs an environment script.
+ """\
+ Runs an environment script.
:param product_info Config: The product description
:param logger Logger: The logger instance to display messages
traceback.print_exc()
def run_simple_env_script(self, script_path, logger=None):
- """Runs an environment script. Same as run_env_script, but with a
- script path as parameter.
+ """\
+ Runs an environment script. Same as run_env_script, but with a
+ script path as parameter.
:param script_path str: a path to an environment script
:param logger Logger: The logger instance to display messages
traceback.print_exc()
def set_products(self, logger, src_root=None):
- """Sets the environment for all the products.
+ """\
+ Sets the environment for all the products.
:param logger Logger: The logger instance to display messages
:param src_root src: the application working directory
self.finish(False)
def set_full_environ(self, logger, env_info):
- """Sets the full environment for products
- specified in env_info dictionary.
+ """\
+ Sets the full environment for products
+ specified in env_info dictionary.
:param logger Logger: The logger instance to display messages
:param env_info list: the list of products
self.set_a_product(product, logger)
class FileEnvWriter:
- """Class to dump the environment to a file.
+ """\
+ Class to dump the environment to a file.
"""
def __init__(self, config, logger, out_dir, src_root, env_info=None):
- '''Initialization.
+ """\
+ Initialization.
:param cfg Config: the global config
:param logger Logger: The logger instance to display messages
:param out_dir str: The directory path where t put the output files
:param src_root str: The application working directory
:param env_info str: The list of products to add in the files.
- '''
+ """
self.config = config
self.logger = logger
self.out_dir = out_dir
self.env_info = env_info
def write_env_file(self, filename, forBuild, shell, for_package = None):
- """Create an environment file.
+ """\
+ Create an environment file.
:param filename str: the file path
:param forBuild bool: if true, the build environment
additional_env = {},
for_package = None,
with_commercial = True):
- """Append to current opened aFile a cfgForPy
- environment (SALOME python launcher).
+ """\
+ Append to current opened aFile a cfgForPy
+ environment (SALOME python launcher).
:param filename str: the file path
:param additional_env dict: a dictionary of additional variables
env.finish(True)
class Shell:
- """Definition of a Shell.
+ """\
+ Definition of a Shell.
"""
def __init__(self, name, extension):
- '''Initialization.
+ """\
+ Initialization.
:param name str: the shell name
:param extension str: the shell extension
- '''
+ """
self.name = name
self.extension = extension
def load_environment(config, build, logger):
- """Loads the environment (used to run the tests, for example).
+ """\
+ Loads the environment (used to run the tests, for example).
:param config Config: the global config
:param build bool: build environement if True
import pprint as PP
import src.debug as DBG
-bat_header="""@echo off
+bat_header="""\
+@echo off
rem The following variables are used only in case of a sat package
set out_dir_Path=%~dp0
"""
-bash_header="""#!/bin/bash
+bash_header="""\
+#!/bin/bash
##########################################################################
#
#### cleandup ###
###########################################################################
"""
-cfg_header='''[SALOME Configuration]
-'''
+cfg_header="""\
+[SALOME Configuration]
+"""
-Launcher_header='''# a generated SALOME Configuration file using python syntax
-'''
+Launcher_header="""\
+# a generated SALOME Configuration file using python syntax
+"""
def get_file_environ(output, shell, environ=None):
"""Instantiate correct FileEnvironment sub-class.
raise Exception("FileEnviron: Unknown shell = %s" % shell)
class FileEnviron(object):
- """Base class for shell environment
+ """\
+ Base class for shell environment
"""
def __init__(self, output, environ=None):
- """Initialization
+ """\
+ Initialization
:param output file: the output file stream.
:param environ dict: a potential additional environment.
self._do_init(output, environ)
def __repr__(self):
- """easy non exhaustive quick resume for debug print"""
+ """\
+ easy non exhaustive quick resume for debug print"""
res = {
"output" : self.output,
"environ" : self.environ,
def _do_init(self, output, environ=None):
- """Initialization
+ """\
+ Initialization
:param output file: the output file stream.
:param environ dict: a potential additional environment.
self.environ = dict(os.environ) #make a copy cvw 180320
def add_line(self, number):
- """Add some empty lines in the shell file
+ """\
+ Add some empty lines in the shell file
:param number int: the number of lines to add
"""
self.output.write("\n" * number)
def add_comment(self, comment):
- """Add a comment in the shell file
+ """\
+ Add a comment in the shell file
:param comment str: the comment to add
"""
self.output.write("# %s\n" % comment)
def add_echo(self, text):
- """Add a "echo" in the shell file
+ """\
+ Add a "echo" in the shell file
:param text str: the text to echo
"""
self.output.write('echo %s"\n' % text)
def add_warning(self, warning):
- """Add a warning "echo" in the shell file
+ """\
+ Add a warning "echo" in the shell file
:param warning str: the text to echo
"""
self.output.write('echo "WARNING %s"\n' % warning)
def append_value(self, key, value, sep=os.pathsep):
- '''append value to key using sep
+ """\
+ append value to key using sep
:param key str: the environment variable to append
:param value str: the value to append to key
:param sep str: the separator string
- '''
+ """
self.set(key, self.get(key) + sep + value)
if (key, sep) not in self.toclean:
self.toclean.append((key, sep))
def append(self, key, value, sep=os.pathsep):
- '''Same as append_value but the value argument can be a list
+ """\
+ Same as append_value but the value argument can be a list
:param key str: the environment variable to append
:param value str or list: the value(s) to append to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
self.append_value(key, sep.join(value), sep)
else:
self.append_value(key, value, sep)
def prepend_value(self, key, value, sep=os.pathsep):
- '''prepend value to key using sep
+ """\
+ prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
:param sep str: the separator string
- '''
+ """
self.set(key, value + sep + self.get(key))
if (key, sep) not in self.toclean:
self.toclean.append((key, sep))
def prepend(self, key, value, sep=os.pathsep):
- '''Same as prepend_value but the value argument can be a list
+ """\
+ Same as prepend_value but the value argument can be a list
:param key str: the environment variable to prepend
:param value str or list: the value(s) to prepend to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
self.prepend_value(key, sep.join(value), sep)
else:
self.prepend_value(key, value, sep)
def is_defined(self, key):
- '''Check if the key exists in the environment
+ """\
+ Check if the key exists in the environment
:param key str: the environment variable to check
- '''
+ """
return (key in self.environ)
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """\
+ Set the environment variable 'key' to value 'value'
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
raise NotImplementedError("set is not implement for this shell!")
def get(self, key):
- '''Get the value of the environment variable "key"
+ """\
+ Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
return '${%s}' % key
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key.
- Has to be overwritten in the derived classes
- This can be seen as a virtual method
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key.
+ Has to be overwritten in the derived classes
+ This can be seen as a virtual method
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
raise NotImplementedError("command_value is not implement "
"for this shell!")
self.output.write('clean %s "%s"\n' % (key, sep))
class BashFileEnviron(FileEnviron):
- """Class for bash shell.
+ """\
+ Class for bash shell.
"""
def __init__(self, output, environ=None):
"""Initialization
self.output.write(bash_header)
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
self.output.write('export %s="%s"\n' % (key, value))
self.environ[key] = value
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key.
- Has to be overwritten in the derived classes
- This can be seen as a virtual method
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key.
+ Has to be overwritten in the derived classes
+ This can be seen as a virtual method
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
self.output.write('export %s=$(%s)\n' % (key, command))
def finish(self, required=True):
FileEnviron.finish(self, required)
class BatFileEnviron(FileEnviron):
- """for Windows batch shell.
+ """\
+ for Windows batch shell.
"""
def __init__(self, output, environ=None):
"""Initialization
self.output.write("rem %s\n" % comment)
def get(self, key):
- '''Get the value of the environment variable "key"
+ """Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
return '%%%s%%' % key
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
self.output.write('set %s=%s\n' % (key, value))
self.environ[key] = value
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key.
- Has to be overwritten in the derived classes
- This can be seen as a virtual method
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key.
+ Has to be overwritten in the derived classes
+ This can be seen as a virtual method
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
self.output.write('%s > tmp.txt\n' % (command))
self.output.write('set /p %s =< tmp.txt\n' % (key))
def finish(self, required=True):
- """Add a final instruction in the out file (in case of file generation)
- In the particular windows case, do nothing
+ """\
+ Add a final instruction in the out file (in case of file generation)
+ In the particular windows case, do nothing
:param required bool: Do nothing if required is False
"""
self.output.write(cfg_header)
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
self.output.write('%s="%s"\n' % (key, value))
self.environ[key] = value
def get(self, key):
- '''Get the value of the environment variable "key"
+ """Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
return '%({0})s'.format(key)
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key.
- Has to be overwritten in the derived classes
- This can be seen as a virtual method
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key.
+ Has to be overwritten in the derived classes
+ This can be seen as a virtual method
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
raise NotImplementedError("command_value is not implement "
"for salome context files!")
self.add_comment("WARNING %s" % warning)
def prepend_value(self, key, value, sep=os.pathsep):
- '''prepend value to key using sep
+ """prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
:param sep str: the separator string
- '''
+ """
self.output.write('ADD_TO_%s: %s\n' % (key, value))
def append_value(self, key, value, sep=os.pathsep):
- '''append value to key using sep
+ """append value to key using sep
:param key str: the environment variable to append
:param value str: the value to append to key
:param sep str: the separator string
- '''
+ """
self.prepend_value(key, value)
def finish(self, required=True):
return
def special_path_separator(name):
- """TCLLIBPATH, TKLIBPATH, PV_PLUGIN_PATH environments variables need
- some exotic path separator.
- This function gives the separator regarding the name of the variable
- to append or prepend.
+ """\
+ TCLLIBPATH, TKLIBPATH, PV_PLUGIN_PATH environments variables need
+ some exotic path separator.
+ This function gives the separator regarding the name of the variable
+ to append or prepend.
:param name str: The name of the variable to find the separator
"""
return res
class LauncherFileEnviron:
- """Class to generate a launcher file script
- (in python syntax) SalomeContext API
+ """\
+ Class to generate a launcher file script
+ (in python syntax) SalomeContext API
"""
def __init__(self, output, environ=None):
"""Initialization
"PYTHONPATH": "PythonPath"}
def change_to_launcher(self, value):
- """
- """
res=value
return res
self.output.write('# "WARNING %s"\n' % warning)
def append_value(self, key, value, sep=":"):
- '''append value to key using sep
+ """append value to key using sep
:param key str: the environment variable to append
:param value str: the value to append to key
:param sep str: the separator string
- '''
+ """
if self.is_defined(key) :
self.add(key, value)
else :
self.set(key, value)
def append(self, key, value, sep=":"):
- '''Same as append_value but the value argument can be a list
+ """Same as append_value but the value argument can be a list
:param key str: the environment variable to append
:param value str or list: the value(s) to append to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
self.append_value(key, sep.join(value), sep)
else:
self.append_value(key, value, sep)
def prepend_value(self, key, value, sep=":"):
- '''prepend value to key using sep
+ """prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
:param sep str: the separator string
- '''
+ """
if self.is_defined(key) :
self.add(key, value)
else :
self.set(key, value)
def prepend(self, key, value, sep=":"):
- '''Same as prepend_value but the value argument can be a list
+ """Same as prepend_value but the value argument can be a list
:param key str: the environment variable to prepend
:param value str or list: the value(s) to prepend to key
:param sep str: the separator string
- '''
+ """
if isinstance(value, list):
self.prepend_value(key, sep.join(value), sep)
else:
self.prepend_value(key, value, sep)
def is_defined(self, key):
- '''Check if the key exists in the environment
+ """Check if the key exists in the environment
:param key str: the environment variable to check
- '''
+ """
return key in self.environ.keys()
def get(self, key):
- '''Get the value of the environment variable "key"
+ """Get the value of the environment variable "key"
:param key str: the environment variable
- '''
+ """
return '${%s}' % key
def set(self, key, value):
- '''Set the environment variable "key" to value "value"
+ """Set the environment variable "key" to value "value"
:param key str: the environment variable to set
:param value str: the value
- '''
+ """
self.output.write(self.begin+self.setVarEnv+
'(r"%s", r"%s", overwrite=True)\n' %
(key, self.change_to_launcher(value)))
self.environ[key] = value
def add(self, key, value):
- '''prepend value to key using sep
+ """prepend value to key using sep
:param key str: the environment variable to prepend
:param value str: the value to prepend to key
- '''
+ """
if key in self.specialKeys.keys():
self.output.write(self.begin+'addTo%s(r"%s")\n' %
(self.specialKeys[key],
self.environ[key]+=sep+value #here yes we know os for current execution
def command_value(self, key, command):
- '''Get the value given by the system command "command"
- and put it in the environment variable key.
+ """\
+ Get the value given by the system command "command"
+ and put it in the environment variable key.
:param key str: the environment variable
:param command str: the command to execute
- '''
+ """
self.output.write(self.indent+'#`%s`\n' % command)
import shlex, subprocess
self.output.write(self.indent+"# %s\n" % comment)
def finish(self, required=True):
- """Add a final instruction in the out file (in case of file generation)
- In the particular launcher case, do nothing
+ """\
+ Add a final instruction in the out file (in case of file generation)
+ In the particular launcher case, do nothing
:param required bool: Do nothing if required is False
"""
self.write("load", script, "", sign="")
# The SALOME launcher template
-withProfile = """#! /usr/bin/env python
+withProfile = """\
+ #! /usr/bin/env python
################################################################
# WARNING: this file is automatically generated by SalomeTools #
sys.exit(1)
#
def addToSpecial(self, name, value, pathSep=None):
- "add special dangerous cases: TCLLIBPATH PV_PLUGIN_PATH etc..."
- #http://computer-programming-forum.com/57-tcl/1dfddc136afccb94.htm
- #TCLLIBPATH: Tcl treats the contents of that variable as a list. Be happy, for you can now use drive letters on windows.
+ # add special dangerous cases: TCLLIBPATH PV_PLUGIN_PATH etc...
+ # http://computer-programming-forum.com/57-tcl/1dfddc136afccb94.htm
+ # TCLLIBPATH: Tcl treats the contents of that variable as a list. Be happy, for you can now use drive letters on windows.
if value == '':
return
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-'''In this file are implemented the classes and method relative to the logging
-'''
+
+"""\
+Implements the classes and method relative to the logging
+"""
import sys
import os
log_all_command_file_expression = "^.*[0-9]{8}_+[0-9]{6}_+.*\.xml$"
class Logger(object):
- '''Class to handle log mechanism.
- '''
+ """\
+ Class to handle log mechanism.
+ """
def __init__(self,
config,
silent_sysstd=False,
all_in_terminal=False,
micro_command = False):
- '''Initialization
+ """Initialization
:param config pyconf.Config: The global configuration.
:param silent_sysstd boolean: if True, do not write anything
in terminal.
- '''
+ """
self.config = config
self.default_level = 3
self.silentSysStd = silent_sysstd
self.logTxtFile = sys.__stdout__
def put_initial_xml_fields(self):
- '''Method called at class initialization : Put all fields
- corresponding to the command context (user, time, ...)
- '''
+ """\
+ Called at class initialization: Put all fields
+ corresponding to the command context (user, time, ...)
+ """
# command name
self.xmlFile.add_simple_node("Site", attrib={"command" :
self.config.VARS.command})
command_name,
command_res,
full_launched_command):
- '''Add a link to another log file.
+ """Add a link to another log file.
:param log_file_name str: The file name of the link.
:param command_name str: The name of the command linked.
:param command_res str: The result of the command linked. "0" or "1"
:parma full_launched_command str: The full lanch command
("sat command ...")
- '''
+ """
xmlLinks = self.xmlFile.xmlroot.find("Links")
src.xmlManager.add_simple_node(xmlLinks,
"link",
"launchedCommand" : full_launched_command})
def write(self, message, level=None, screenOnly=False):
- '''the function used in the commands
- that will print in the terminal and the log file.
+ """\
+ function used in the commands
+ to print in the terminal and the log file.
:param message str: The message to print.
:param level int: The output level corresponding
to the message 0 < level < 6.
:param screenOnly boolean: if True, do not write in log file.
- '''
+ """
# do not write message starting with \r to log file
if not message.startswith("\r") and not screenOnly:
self.xmlFile.append_node_text("Log",
self.flush()
def error(self, message):
- '''Print an error.
+ """Print an error.
:param message str: The message to print.
- '''
+ """
# Print in the log file
self.xmlFile.append_node_text("traces", _('ERROR:') + message)
sys.stderr.write(_('ERROR:') + message)
def flush(self):
- '''Flush terminal
- '''
+ """Flush terminal"""
sys.stdout.flush()
self.logTxtFile.flush()
def end_write(self, attribute):
- '''Method called just after command end : Put all fields
- corresponding to the command end context (time).
- Write the log xml file on the hard drive.
- And display the command to launch to get the log
+ """\
+ Called just after command end: Put all fields
+ corresponding to the command end context (time).
+ Write the log xml file on the hard drive.
+ And display the command to launch to get the log
:param attribute dict: the attribute to add to the node "Site".
- '''
+ """
# Get current time (end of command) and format it
dt = datetime.datetime.now()
Y, m, dd, H, M, S = date_to_datetime(self.config.VARS.datehour)
pass
def date_to_datetime(date):
- '''Little method that gets year, mon, day, hour ,
- minutes and seconds from a str in format YYYYMMDD_HHMMSS
+ """\
+ From a string date in format YYYYMMDD_HHMMSS
+ returns list year, mon, day, hour, minutes, seconds
:param date str: The date in format YYYYMMDD_HHMMSS
:return: the same date and time in separate variables.
:rtype: (str,str,str,str,str,str)
- '''
+ """
Y = date[:4]
m = date[4:6]
dd = date[6:8]
return Y, m, dd, H, M, S
def timedelta_total_seconds(timedelta):
- '''Little method to replace total_seconds from
- datetime module in order to be compatible with old python versions
+ """\
+ Replace total_seconds from datetime module
+ in order to be compatible with old python versions
:param timedelta datetime.timedelta: The delta between two dates
:return: The number of seconds corresponding to timedelta.
:rtype: float
- '''
+ """
return (
timedelta.microseconds + 0.0 +
(timedelta.seconds + timedelta.days * 24 * 3600) * 10 ** 6) / 10 ** 6
def show_command_log(logFilePath, cmd, application, notShownCommands):
- '''Used in updateHatXml. Determine if the log xml file logFilePath
- has to be shown or not in the hat log.
+ """\
+ Used in updateHatXml.
+ Determine if the log xml file logFilePath
+ has to be shown or not in the hat log.
:param logFilePath str: the path to the command xml log file
:param cmd str: the command of the log file
:return: True if cmd is not in notShownCommands and the application
in the log file corresponds to application
:rtype: boolean
- '''
+ """
# When the command is not in notShownCommands, no need to go further :
# Do not show
if cmd in notShownCommands:
return False, None, None
def list_log_file(dirPath, expression):
- '''Find all files corresponding to expression in dirPath
+ """Find all files corresponding to expression in dirPath
:param dirPath str: the directory where to search the files
:param expression str: the regular expression of files to find
:return: the list of files path and informations about it
:rtype: list
- '''
+ """
lRes = []
for fileName in os.listdir(dirPath):
# YYYYMMDD_HHMMSS_namecmd.xml
return lRes
def update_hat_xml(logDir, application=None, notShownCommands = []):
- '''Create the xml file in logDir that contain all the xml file
- and have a name like YYYYMMDD_HHMMSS_namecmd.xml
+ """\
+ Create the xml file in logDir that contain all the xml file
+ and have a name like YYYYMMDD_HHMMSS_namecmd.xml
:param logDir str: the directory to parse
:param application str: the name of the application if there is any
- '''
+ """
# Create an instance of XmlLogFile class to create hat.xml file
xmlHatFilePath = os.path.join(logDir, 'hat.xml')
xmlHat = src.xmlManager.XmlLogFile(xmlHatFilePath,
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-'''In this file are implemented the methods
- relative to the product notion of salomeTools
-'''
+
+"""\
+In this file are implemented the methods
+relative to the product notion of salomeTools
+"""
import os
import re
VERSION_DELIMITER = "_to_"
def get_product_config(config, product_name, with_install_dir=True):
- '''Get the specific configuration of a product from the global configuration
+ """Get the specific configuration of a product from the global configuration
:param config Config: The global configuration
:param product_name str: The name of the product
of the function check_config_exists)
:return: the specific configuration of the product
:rtype: Config
- '''
+ """
# Get the version of the product from the application definition
version = config.APPLICATION.products[product_name]
DBG.tofix(msg, config.PATHS.ARCHIVEPATH) #avoid 2 messages in compile
prod_info.archive_info.archive_name = arch_name #without path
# raise src.SatException(msg) #may be a warning, continue #8646
- else:
- prod_info.archive_info.archive_name = arch_path
-
+ prod_info.archive_info.archive_name = arch_path
# If the product compiles with a script, check the script existence
# and if it is executable
return prod_info
def get_product_section(config, product_name, version, section=None):
- '''Get the product description from the configuration
+ """Get the product description from the configuration
:param config Config: The global configuration
:param product_name str: The product name
explicitly given
:return: The product description
:rtype: Config
- '''
+ """
# if section is not None, try to get the corresponding section
if section:
return None
def get_install_dir(config, base, version, prod_info):
- '''Compute the installation directory of a given product
+ """Compute the installation directory of a given product
:param config Config: The global configuration
:param base str: This corresponds to the value given by user in its
application.pyconf for the specific product. If "yes", the
- user wants the product to be in base. If "no", he wants the
- product to be in the application workdir
+ user wants the product to be in base. If "no", he wants the
+ product to be in the application workdir
:param version str: The version of the product
:param product_info Config: The configuration specific to
the product
:return: The path of the product installation
:rtype: str
- '''
+ """
install_dir = ""
in_base = False
if (("install_dir" in prod_info and prod_info.install_dir == "base")
return install_dir
def get_base_install_dir(config, prod_info, version):
- '''Compute the installation directory of a product in base
+ """Compute the installation directory of a product in base
:param config Config: The global configuration
:param product_info Config: The configuration specific to
:param version str: The version of the product
:return: The path of the product installation
:rtype: str
- '''
+ """
base_path = src.get_base_path(config)
prod_dir = os.path.join(base_path, prod_info.name + "-" + version)
if not os.path.exists(prod_dir):
return install_dir
def check_config_exists(config, prod_dir, prod_info):
- '''Verify that the installation directory of a product in a base exists
- Check all the config-<i> directory and verify the sat-config.pyconf file
- that is in it
+ """\
+ Verify that the installation directory of a product in a base exists
+ Check all the config-<i> directory and verify the sat-config.pyconf file
+ that is in it
:param config Config: The global configuration
:param prod_dir str: The product installation directory path
:return: True or false is the installation is found or not
and if it is found, the path of the found installation
:rtype: (boolean, str)
- '''
+ """
# check if the directories or files of the directory corresponds to the
# directory installation of the product
l_dir_and_files = os.listdir(prod_dir)
def get_products_infos(lproducts, config):
- '''Get the specific configuration of a list of products
+ """Get the specific configuration of a list of products
:param lproducts List: The list of product names
:param config Config: The global configuration
:return: the list of tuples
(product name, specific configuration of the product)
:rtype: [(str, Config)]
- '''
+ """
products_infos = []
# Loop on product names
for prod in lproducts:
return products_infos
def get_product_dependencies(config, product_info):
- '''Get recursively the list of products that are
- in the product_info dependencies
+ """\
+ Get recursively the list of products that are
+ in the product_info dependencies
:param config Config: The global configuration
:param product_info Config: The configuration specific to
the product
:return: the list of products in dependence
:rtype: list
- '''
+ """
if "depend" not in product_info or product_info.depend == []:
return []
res = []
return res
def check_installation(product_info):
- '''Verify if a product is well installed. Checks install directory presence
- and some additional files if it is defined in the config
+ """\
+ Verify if a product is well installed. Checks install directory presence
+ and some additional files if it is defined in the config
:param product_info Config: The configuration specific to
the product
:return: True if it is well installed
:rtype: boolean
- '''
+ """
if not product_compiles(product_info):
return True
install_dir = product_info.install_dir
return True
def check_source(product_info):
- '''Verify if a sources of product is preset. Checks source directory presence
+ """Verify if a sources of product is preset. Checks source directory presence
:param product_info Config: The configuration specific to
the product
:return: True if it is well installed
:rtype: boolean
- '''
+ """
DBG.write("check_source product_info", product_info)
source_dir = product_info.source_dir
if not os.path.exists(source_dir):
return False
return True
+def product_is_sample(product_info):
+ """Know if a product has the sample type
+
+ :param product_info Config: The configuration specific to
+ the product
+ :return: True if the product has the sample type, else False
+ :rtype: boolean
+ """
+ if 'type' in product_info:
+ ptype = product_info.type
+ return ptype.lower() == 'sample'
+ else:
+ return False
+
def product_is_salome(product_info):
- '''Know if a product is a SALOME module
+ """Know if a product is a SALOME module
:param product_info Config: The configuration specific to
the product
:return: True if the product is a SALOME module, else False
:rtype: boolean
- '''
+ """
return ("properties" in product_info and
"is_SALOME_module" in product_info.properties and
product_info.properties.is_SALOME_module == "yes")
def product_is_fixed(product_info):
- '''Know if a product is fixed
+ """Know if a product is fixed
:param product_info Config: The configuration specific to
the product
:return: True if the product is fixed, else False
:rtype: boolean
- '''
+ """
get_src = product_info.get_source
return get_src.lower() == 'fixed'
def product_is_native(product_info):
- '''Know if a product is native
+ """Know if a product is native
:param product_info Config: The configuration specific to
the product
:return: True if the product is native, else False
:rtype: boolean
- '''
+ """
get_src = product_info.get_source
return get_src.lower() == 'native'
def product_is_dev(product_info):
- '''Know if a product is in dev mode
+ """Know if a product is in dev mode
:param product_info Config: The configuration specific to
the product
:return: True if the product is in dev mode, else False
:rtype: boolean
- '''
+ """
dev = product_info.dev
res = (dev.lower() == 'yes')
DBG.write('product_is_dev %s' % product_info.name, res)
return res
def product_is_debug(product_info):
- '''Know if a product is in debug mode
+ """Know if a product is in debug mode
:param product_info Config: The configuration specific to
the product
:return: True if the product is in debug mode, else False
:rtype: boolean
- '''
+ """
debug = product_info.debug
return debug.lower() == 'yes'
def product_is_autotools(product_info):
- '''Know if a product is compiled using the autotools
+ """Know if a product is compiled using the autotools
:param product_info Config: The configuration specific to
the product
:return: True if the product is autotools, else False
:rtype: boolean
- '''
+ """
build_src = product_info.build_source
return build_src.lower() == 'autotools'
def product_is_cmake(product_info):
- '''Know if a product is compiled using the cmake
+ """Know if a product is compiled using the cmake
:param product_info Config: The configuration specific to
the product
:return: True if the product is cmake, else False
:rtype: boolean
- '''
+ """
build_src = product_info.build_source
return build_src.lower() == 'cmake'
def product_is_vcs(product_info):
- '''Know if a product is download using git, svn or cvs (not archive)
+ """Know if a product is download using git, svn or cvs (not archive)
:param product_info Config: The configuration specific to
the product
:return: True if the product is vcs, else False
:rtype: boolean
- '''
+ """
return product_info.get_source in AVAILABLE_VCS
def product_is_smesh_plugin(product_info):
- '''Know if a product is a SMESH plugin
+ """Know if a product is a SMESH plugin
:param product_info Config: The configuration specific to
the product
:return: True if the product is a SMESH plugin, else False
:rtype: boolean
- '''
+ """
return ("properties" in product_info and
"smesh_plugin" in product_info.properties and
product_info.properties.smesh_plugin == "yes")
def product_is_cpp(product_info):
- '''Know if a product is cpp
+ """Know if a product is cpp
:param product_info Config: The configuration specific to
the product
:return: True if the product is a cpp, else False
:rtype: boolean
- '''
+ """
return ("properties" in product_info and
"cpp" in product_info.properties and
product_info.properties.cpp == "yes")
def product_compiles(product_info):
- '''Know if a product compiles or not (some products do not have a
- compilation procedure)
+ """\
+ Know if a product compiles or not
+ (some products do not have a compilation procedure)
:param product_info Config: The configuration specific to
the product
:return: True if the product compiles, else False
:rtype: boolean
- '''
+ """
return not("properties" in product_info and
"compilation" in product_info.properties and
product_info.properties.compilation == "no")
def product_has_script(product_info):
- '''Know if a product has a compilation script
+ """Know if a product has a compilation script
:param product_info Config: The configuration specific to
the product
:return: True if the product it has a compilation script, else False
:rtype: boolean
- '''
+ """
if "build_source" not in product_info:
# Native case
return False
return build_src.lower() == 'script'
def product_has_env_script(product_info):
- '''Know if a product has an environment script
+ """Know if a product has an environment script
:param product_info Config: The configuration specific to
the product
:return: True if the product it has an environment script, else False
:rtype: boolean
- '''
+ """
return "environ" in product_info and "env_script" in product_info.environ
def product_has_patches(product_info):
- '''Know if a product has one or more patches
+ """Know if a product has one or more patches
:param product_info Config: The configuration specific to
the product
:return: True if the product has one or more patches
:rtype: boolean
- '''
+ """
res = ( "patches" in product_info and len(product_info.patches) > 0 )
DBG.write('product_has_patches %s' % product_info.name, res)
# if product_info.name == "XDATA": return True #test #10569
return res
def product_has_logo(product_info):
- '''Know if a product has a logo (YACSGEN generate)
+ """Know if a product has a logo (YACSGEN generate)
:param product_info Config: The configuration specific to
the product
:return: The path of the logo if the product has a logo, else False
:rtype: Str
- '''
+ """
if ("properties" in product_info and
"logo" in product_info.properties):
return product_info.properties.logo
return False
def product_has_salome_gui(product_info):
- '''Know if a product has a SALOME gui
+ """Know if a product has a SALOME gui
:param product_info Config: The configuration specific to
the product
:return: True if the product has a SALOME gui, else False
:rtype: Boolean
- '''
+ """
return ("properties" in product_info and
"has_salome_gui" in product_info.properties and
product_info.properties.has_salome_gui == "yes")
def product_is_mpi(product_info):
- '''Know if a product has openmpi in its dependencies
+ """Know if a product has openmpi in its dependencies
:param product_info Config: The configuration specific to
the product
:return: True if the product has openmpi inits dependencies
:rtype: boolean
- '''
+ """
return "openmpi" in product_info.depend
def product_is_generated(product_info):
- '''Know if a product is generated (YACSGEN)
+ """Know if a product is generated (YACSGEN)
:param product_info Config: The configuration specific to
the product
:return: True if the product is generated
:rtype: boolean
- '''
+ """
return ("properties" in product_info and
"generate" in product_info.properties and
product_info.properties.generate == "yes")
def get_product_components(product_info):
- '''Get the component list to generate with the product
+ """Get the component list to generate with the product
:param product_info Config: The configuration specific to
the product
:return: The list of names of the components
:rtype: List
- '''
+ """
if not product_is_generated(product_info):
return []
self.stream.close()
def defaultStreamOpener(name):
- """
+ """\
This function returns a read-only stream, given its name. The name passed
in should correspond to an existing stream, otherwise an exception will be
raised.
return s.isalnum()
def makePath(prefix, suffix):
- """
+ """\
Make a path from a prefix and suffix.
- Examples::
-
- makePath('', 'suffix') -> 'suffix'
- makePath('prefix', 'suffix') -> 'prefix.suffix'
- makePath('prefix', '[1]') -> 'prefix[1]'
-
- @param prefix: The prefix to use. If it evaluates as false, the suffix
- is returned.
- @type prefix: str
- @param suffix: The suffix to use. It is either an identifier or an
- index in brackets.
- @type suffix: str
- @return: The path concatenation of prefix and suffix, with a
- dot if the suffix is not a bracketed index.
- @rtype: str
+ Examples:
+ makePath('', 'suffix') -> 'suffix'
+ makePath('prefix', 'suffix') -> 'prefix.suffix'
+ makePath('prefix', '[1]') -> 'prefix[1]'
+ @param prefix: The prefix to use. If it evaluates as false, the suffix is returned.
+ @type prefix: str
+ @param suffix: The suffix to use. It is either an identifier or an index in brackets.
+ @type suffix: str
+ @return: The path concatenation of prefix and suffix, with adot if the suffix is not a bracketed index.
+ @rtype: str
"""
if not prefix:
rv = suffix
ref.addElement(LBRACK, tv)
def defaultMergeResolve(map1, map2, key):
- """
- A default resolver for merge conflicts. Returns a string
- indicating what action to take to resolve the conflict.
+ """\
+ A default resolver for merge conflicts.
+ Returns a string indicating what action to take to resolve the conflict.
@param map1: The map being merged into.
@type map1: L{Mapping}.
@type map2: L{Mapping}.
@param key: The key in map2 (which also exists in map1).
@type key: str
+
@return: One of "merge", "append", "mismatch" or "overwrite"
indicating what action should be taken. This should
be appropriate to the objects being merged - e.g.
there is no point returning "merge" if the two objects
are instances of L{Sequence}.
+
@rtype: str
"""
obj1 = map1[key]
