Add rendered docs for gh-pages delivery

Scheme based on sphinx-doc/sphinx#3382 (comment)
mozilla · Aug 4, 2020 · 22c145f · 22c145f
1 parent bdae95f
commit 22c145f
Show file tree

Hide file tree

Showing 34 changed files with 16,027 additions and 0 deletions.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 07c966ec7863c8a9e214c5ee2bd399ef
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_build/html/Architecture.html b/docs/_build/html/Architecture.html
@@ -0,0 +1,173 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Architecture &#8212; Frost  documentation</title>
+    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script src="_static/jquery.js"></script>
+    <script src="_static/underscore.js"></script>
+    <script src="_static/doctools.js"></script>
+    <script src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Conventions" href="CodingConventions.html" />
+    <link rel="prev" title="Frequently Asked Questions" href="FAQ.html" />
+
+  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+
+
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+  </head><body>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+
+
+          <div class="body" role="main">
+
+  <!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at https://mozilla.org/MPL/2.0/. --><div class="section" id="architecture">
+<span id="id1"></span><h1>Architecture<a class="headerlink" href="#architecture" title="Permalink to this headline">¶</a></h1>
+<p>PyTest supports several different ways of organizing tests. For frost, we use a
+mixture of class based and declarative tests.</p>
+<p>In general the class holds session information, as PyTest treats class
+<code class="docutils literal notranslate"><span class="pre">__init__</span></code> functions as session scoped fixtures. The class methods provide raw
+access to the service, and cache the result.</p>
+<p>Traditional PyTest fixtures (in <code class="docutils literal notranslate"><span class="pre">conftest.py</span></code>) or “cache access functions” (in
+<code class="docutils literal notranslate"><span class="pre">resources.py</span></code>) are used to supply the data to tests. The tests are
+conventionally written in <code class="docutils literal notranslate"><span class="pre">test_&lt;foo&gt;.py</span></code> files, with a single function of the
+same name as the file. <em>(With “Black_”, we stopped the tabs-vs-spaces debate,
+so redirected that energy to one-or-many-tests-per-file debate.)</em></p>
+<p>A recommended way to organize your code is to create a directory per type of
+resource you test. E.g. <code class="docutils literal notranslate"><span class="pre">aws/{elb,ec2,iam}/</span></code> or
+<code class="docutils literal notranslate"><span class="pre">github/{orgs,branches,users}</span></code>. Whether it makes sense to have <code class="docutils literal notranslate"><span class="pre">conftest.py</span></code>
+files at each level is up to the developer. There should only be one session
+client per service though.</p>
+<div class="section" id="caching">
+<h2>Caching<a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h2>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The caching operations is under consideration for deprecation. If you
+intend to rely on caching, you should check with the active developers first.</p>
+</div>
+<p>To implement caching:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><p>Your class <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method must accept and store a cache object.</p></li>
+<li><dl class="simple">
+<dt>Your data retrieval functions should be written to try the cache first</dt><dd><p>before fetching data from the service under test.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt>A cache_key global function is recommended as a means to ensure consistent</dt><dd><p>and non conflicting keys to store data in the cache. (The existing
+functions tend to marshal the full data location path and arguments
+into a string.)</p>
+</dd>
+</dl>
+</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="expected-output-flow">
+<h2>Expected Output flow<a class="headerlink" href="#expected-output-flow" title="Permalink to this headline">¶</a></h2>
+<p>Every test that fails needs to output sufficient information to allow downstream
+processes to take action on the failure (open an issue, or bug, or email the
+team or …). All that information must be contained in the test id. Use the
+<code class="docutils literal notranslate"><span class="pre">ids</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">pytest.mark.parametrize</span></code> decorator to generate rich
+ids as needed. (See <a class="reference external" href="https://docs.pytest.org/en/stable/example/parametrize.html#paramexamples&gt;`)">PyTest docs</a>.)</p>
+<p>A PyTest plugin in frost adds the option <code class="docutils literal notranslate"><span class="pre">--json</span></code> which outputs test failures
+as JSON objects which include the test’s id, in addition to other context about
+the failed test. Using the <code class="docutils literal notranslate"><span class="pre">--json</span></code> option is the recommended way to provide
+actionalble data to processes further down the pipeline.</p>
+<p>The output flow will be installation specific.</p>
+</div>
+</div>
+
+
+          </div>
+
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="index.html">Frost</a></h1>
+
+
+
+
+
+
+
+
+<h3>Navigation</h3>
+<p class="caption"><span class="caption-text">Contents:</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="FAQ.html">Frequently Asked Questions</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Architecture</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#caching">Caching</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#expected-output-flow">Expected Output flow</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="CodingConventions.html">Conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="MozillaDeployment.html">Mozilla Deployment</a></li>
+<li class="toctree-l1"><a class="reference internal" href="NewServices.html">Adding a New Service</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="FAQ.html" title="previous chapter">Frequently Asked Questions</a></li>
+      <li>Next: <a href="CodingConventions.html" title="next chapter">Conventions</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+
+
+
+
+
+
+
+
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="footer">
+      &copy;2020.
+
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.1.2</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
+
+      |
+      <a href="_sources/Architecture.rst.txt"
+          rel="nofollow">Page source</a>
+    </div>
+
+
+
+
+  </body>
+</html>
diff --git a/docs/_build/html/CodingConventions.html b/docs/_build/html/CodingConventions.html
@@ -0,0 +1,122 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Conventions &#8212; Frost  documentation</title>
+    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script src="_static/jquery.js"></script>
+    <script src="_static/underscore.js"></script>
+    <script src="_static/doctools.js"></script>
+    <script src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Mozilla Deployment" href="MozillaDeployment.html" />
+    <link rel="prev" title="Architecture" href="Architecture.html" />
+
+  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+
+
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+  </head><body>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+
+
+          <div class="body" role="main">
+
+  <!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at https://mozilla.org/MPL/2.0/. --><div class="section" id="conventions">
+<h1>Conventions<a class="headerlink" href="#conventions" title="Permalink to this headline">¶</a></h1>
+<ul class="simple">
+<li><p>As mentioned elsewhere, all function <em>not</em> within a <code class="docutils literal notranslate"><span class="pre">test_*.py</span></code> file should
+have <a class="reference external" href="https://docs.python.org/3.6/library/doctest.html">doctest</a> tests.</p></li>
+<li><p>Frost tests are expected to support the <code class="docutils literal notranslate"><span class="pre">--json</span></code> option by ensuring ids used
+in <code class="docutils literal notranslate"><span class="pre">pytest.mark.parametrize</span></code> contain sufficient information for downstream
+processing.</p></li>
+</ul>
+</div>
+
+
+          </div>
+
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="index.html">Frost</a></h1>
+
+
+
+
+
+
+
+
+<h3>Navigation</h3>
+<p class="caption"><span class="caption-text">Contents:</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="FAQ.html">Frequently Asked Questions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Architecture.html">Architecture</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="MozillaDeployment.html">Mozilla Deployment</a></li>
+<li class="toctree-l1"><a class="reference internal" href="NewServices.html">Adding a New Service</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="Architecture.html" title="previous chapter">Architecture</a></li>
+      <li>Next: <a href="MozillaDeployment.html" title="next chapter">Mozilla Deployment</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+
+
+
+
+
+
+
+
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="footer">
+      &copy;2020.
+
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.1.2</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
+
+      |
+      <a href="_sources/CodingConventions.rst.txt"
+          rel="nofollow">Page source</a>
+    </div>
+
+
+
+
+  </body>
+</html>