--- /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. */
--- /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',
+ }
+})
-***********
-application
-***********
+
+Command application
+*********************
Description
===========
-*******
-compile
-*******
+
+Command compile
+****************
Description
===========
-******
-config
-******
+
+Command config
+******************
Description
===========
-*******
-environ
-*******
+
+Command environ
+****************
Description
===========
-********
-launcher
-********
+
+Command launcher
+******************
Description
===========
-***
-log
-***
+
+
+Command log
+****************
Description
===========
-*******
-prepare
-*******
+
+Command prepare
+****************
Description
===========
# General information about the project.
project = u'salomeTools'
-copyright = u'2010-2016, CEA'
+copyright = u'2010-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'
+html_theme_path = ["../_themes/alabaster", ]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# 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 = "images/sat_v5_small.ico"
# 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,
]
# Append source folder to path in order to enable autodoc
-sys.path.append(os.path.join('..'))
\ No newline at end of file
+sys.path.append(os.path.join('..'))
--- /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*.
+
+
+
+
SAlome Tools
************
-.. note::
-
- This documentation is under construction.
+.. note:: This documentation is under construction.
-SAlomeTools (sat) is a suite of commands that can be used to perform operations on SALOME.
+**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 modules or prerequisites, create an application, run tests, create a package...
+For example, sat allows you to compile SALOME's codes
+(prerequisites, products)
+create application, run tests, create package, etc.
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
================
SAT modules <commands/apidoc/modules.rst>
-developer documentation
+Developer documentation
=======================
.. toctree::
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
+********************
+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*
+
+
