Merge pull request #34 from PagerDuty/migration-guide-update

Clarity updates in the migration guide, retry behavior docs and installation sections (readme/user guide)

README.rst

@@ -8,7 +8,7 @@ For in-depth usage documentation, refer to the `User Guide
 
 Installation
 ------------
-This library is available on PyPI as `pagerduty <https://pypi.org/project/pagerduty/>`_, e.g.: 
+This library is available on the Python Package Index as `pagerduty <https://pypi.org/project/pagerduty/>`_, e.g.: 
 
 .. code-block:: bash
 

docs/pdpyras_migration_guide.html

@@ -85,23 +85,26 @@ <h1>PDPYRAS Migration Guide<a class="headerlink" href="#pdpyras-migration-guide"
 from the original <a class="reference external" href="https://github.com/PagerDuty/pdpyras">pdpyras</a> source code. This was done so that nomenclature
 clearly reflects the hierarchy of APIs and errors, and to make the relationship
 between API clients and their respective APIs more clear.</p>
-<p>The following replacements are expressed in <a class="reference external" href="https://www.gnu.org/software/sed/manual/html_node/The-_0022s_0022-Command.html">sed-style substitution format</a>,
-i.e. if replacing all instances of <code class="docutils literal notranslate"><span class="pre">{{pattern}}</span></code> with <code class="docutils literal notranslate"><span class="pre">{{replacement}}</span></code>:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">s</span><span class="o">/</span><span class="p">{{</span><span class="n">pattern</span><span class="p">}}</span><span class="o">/</span><span class="p">{{</span><span class="n">replacement</span><span class="p">}}</span><span class="o">/</span><span class="n">g</span>
+<p>Replacements are expressed in <a class="reference external" href="https://www.gnu.org/software/sed/manual/html_node/The-_0022s_0022-Command.html">sed-style substitution format</a>,
+i.e. if replacing all instances of <code class="docutils literal notranslate"><span class="pre">{{pattern}}</span></code> with <code class="docutils literal notranslate"><span class="pre">{{replacement}}</span></code>,
+the pattern is <code class="docutils literal notranslate"><span class="pre">s/{{pattern}}/{{replacement}}/g</span></code>.</p>
+<p>The first substitution that should be made is <code class="docutils literal notranslate"><span class="pre">s/pdpyras/pagerduty/g</span></code>, i.e.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="kn">import</span> <span class="nn">pdpyras</span>
+<span class="o">+</span> <span class="kn">import</span> <span class="nn">pagerduty</span>
 </pre></div>
 </div>
 <section id="client-classes">
 <h2>Client Classes<a class="headerlink" href="#client-classes" title="Permalink to this heading"></a></h2>
-<p>In downstream code that uses <a class="reference external" href="https://github.com/PagerDuty/pdpyras">pdpyras</a>, the following name replacements
-should be made in order to switch to using <cite>python-pagerduty</cite>. <strong>The first
+<p>In code that uses <a class="reference external" href="https://github.com/PagerDuty/pdpyras">pdpyras</a>, the following class name replacements should be
+made to switch to using their equivalents in <cite>python-pagerduty</cite>. <strong>The first
 three should be done in the order shown, so as to avoid name overlap issues:</strong></p>
 <ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">s/ChangeEventsAPISession/EventsApiV2Client/g</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">s/EventsAPISession/EventsApiV2Client/g</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">s/APISession/RestApiV2Client/g</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">s/PDSession/ApiClient/g</span></code></p></li>
 </ol>
-<p>The Change Events API client has been merged into the Events API v2 client
+<p>Note, the Change Events API client has been merged into the Events API v2 client
 because the former API is effectively a component of the latter. The
 differences are trivial enough to support both use cases with a single client
 class, and there are no method or property name collisions between the two

docs/user_guide.html

@@ -123,7 +123,7 @@
 has in-depth documentation on client classes and methods.</p>
 <section id="installation">
 <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h2>
-<p>This library is available on PyPI as <a class="reference external" href="https://pypi.org/project/pagerduty/">pagerduty</a>, e.g.:</p>
+<p>This library is available on the Python Package Index as <a class="reference external" href="https://pypi.org/project/pagerduty/">pagerduty</a>, e.g.:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install pagerduty
 </pre></div>
 </div>
@@ -736,13 +736,13 @@ <h3>Exponential Cooldown<a class="headerlink" href="#exponential-cooldown" title
 increases exponentially with each retry.</p>
 <p>Let:</p>
 <ul class="simple">
-<li><p>a = <a class="reference internal" href="module_reference.html#pagerduty.ApiClient.sleep_timer_base" title="pagerduty.ApiClient.sleep_timer_base"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ApiClient.sleep_timer_base</span></code></a></p></li>
-<li><p>t<sub>0</sub> = <code class="docutils literal notranslate"><span class="pre">sleep_timer</span></code></p></li>
+<li><p>a = <a class="reference internal" href="module_reference.html#pagerduty.ApiClient.sleep_timer_base" title="pagerduty.ApiClient.sleep_timer_base"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ApiClient.sleep_timer_base</span></code></a> (base of the exponent, default value <code class="docutils literal notranslate"><span class="pre">2</span></code>)</p></li>
+<li><p>t<sub>0</sub> = <a class="reference internal" href="module_reference.html#pagerduty.ApiClient.sleep_timer" title="pagerduty.ApiClient.sleep_timer"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ApiClient.sleep_timer</span></code></a> (initial sleep timer, default value <code class="docutils literal notranslate"><span class="pre">1.5</span></code>)</p></li>
 <li><p>t<sub>n</sub> = Sleep time after n attempts</p></li>
 <li><p>ρ = <a class="reference internal" href="module_reference.html#pagerduty.ApiClient.stagger_cooldown" title="pagerduty.ApiClient.stagger_cooldown"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ApiClient.stagger_cooldown</span></code></a></p></li>
 <li><p>r<sub>n</sub> = a randomly-generated real number between 0 and 1, distinct for each n-th request</p></li>
 </ul>
-<p>Assuming ρ = 0:</p>
+<p>Assuming ρ = 0 (the default value):</p>
 <p>t<sub>n</sub> = t<sub>0</sub> a<sup>n</sup></p>
 <p>If ρ is nonzero:</p>
 <p>t<sub>n</sub> = a (1 + ρ r<sub>n</sub>) t<sub>n-1</sub></p>

sphinx/source/pdpyras_migration_guide.rst

@@ -9,27 +9,30 @@ from the original `pdpyras`_ source code. This was done so that nomenclature
 clearly reflects the hierarchy of APIs and errors, and to make the relationship
 between API clients and their respective APIs more clear.
 
-The following replacements are expressed in `sed-style substitution format
+Replacements are expressed in `sed-style substitution format
 <https://www.gnu.org/software/sed/manual/html_node/The-_0022s_0022-Command.html>`_,
-i.e. if replacing all instances of ``{{pattern}}`` with ``{{replacement}}``:
+i.e. if replacing all instances of ``{{pattern}}`` with ``{{replacement}}``,
+the pattern is ``s/{{pattern}}/{{replacement}}/g``.
 
-::
+The first substitution that should be made is ``s/pdpyras/pagerduty/g``, i.e.
 
-   s/{{pattern}}/{{replacement}}/g
+::
 
+    - import pdpyras
+    + import pagerduty
 
 Client Classes
 --------------
-In downstream code that uses `pdpyras`_, the following name replacements
-should be made in order to switch to using `python-pagerduty`. **The first
+In code that uses `pdpyras`_, the following class name replacements should be
+made to switch to using their equivalents in `python-pagerduty`. **The first
 three should be done in the order shown, so as to avoid name overlap issues:**
 
 1. ``s/ChangeEventsAPISession/EventsApiV2Client/g``
 2. ``s/EventsAPISession/EventsApiV2Client/g``
 3. ``s/APISession/RestApiV2Client/g``
 4. ``s/PDSession/ApiClient/g``
 
-The Change Events API client has been merged into the Events API v2 client
+Note, the Change Events API client has been merged into the Events API v2 client
 because the former API is effectively a component of the latter. The
 differences are trivial enough to support both use cases with a single client
 class, and there are no method or property name collisions between the two

sphinx/source/user_guide.rst

@@ -11,7 +11,7 @@ has in-depth documentation on client classes and methods.
 
 Installation
 ------------
-This library is available on PyPI as `pagerduty <https://pypi.org/project/pagerduty/>`_, e.g.: 
+This library is available on the Python Package Index as `pagerduty <https://pypi.org/project/pagerduty/>`_, e.g.: 
 
 .. code-block:: bash
 
@@ -705,13 +705,13 @@ increases exponentially with each retry.
 
 Let:
 
-* a = :attr:`pagerduty.ApiClient.sleep_timer_base`
-* t\ :sub:`0` = ``sleep_timer``
+* a = :attr:`pagerduty.ApiClient.sleep_timer_base` (base of the exponent, default value ``2``)
+* t\ :sub:`0` = :attr:`pagerduty.ApiClient.sleep_timer` (initial sleep timer, default value ``1.5``)
 * t\ :sub:`n` = Sleep time after n attempts
 * ρ = :attr:`pagerduty.ApiClient.stagger_cooldown`
 * r\ :sub:`n` = a randomly-generated real number between 0 and 1, distinct for each n-th request
 
-Assuming ρ = 0:
+Assuming ρ = 0 (the default value):
 
 t\ :sub:`n` = t\ :sub:`0` a\ :sup:`n`