[ci skip] Autodoc commit for 056eea4.

develop/_sources/customizations.rst.txt

@@ -38,6 +38,8 @@ directory while members of the ``staff`` Unix group can.
   sudo chown root:staff /var/www/ood/apps/sys/files
 
 
+.. _configure_announcements:
+
 Announcements
 -------------
 
@@ -62,15 +64,25 @@ the user would see this message at the top of the dashboard:
 
 If the announcement file has the extension ``yml`` and is a yaml file it is first rendered using ERB and then the resulting file is parsed as YAML. The valid keys are:
 
-.. list-table:: Config Files
-   :stub-columns: 1
+.. list-table:: Announcement configuration keys.
 
+   * - Key
+     - Description
    * - type
-     - warning, info, success, or danger
-     - this is the Bootstrap alert style
+     - The type of announcment. Values can be ``warning``, ``info``, ``success``, or ``danger``.
    * - msg
-     - string containing markdown formatted message
-     - if this is a blank string (only whitespace), the alert will not display
+     - The announcement's message.
+   * - dismissable
+     - Specify if the announcment is dismissable or not with ``true`` or ``false``.
+       Defaults to ``true``.
+   * - required
+     - Specify if the announcment is required or not with ``true`` or ``false``.
+       Defaults to ``false``. When this is set to ``true``, the user will not be
+       do anything until the announcment has been accepted.
+
+.. tip::
+  You can use ``required`` announcements to present users with a ToS (terms of service),
+  EULA (end user license agreement) or similar.
 
 Because the announcement is rendered via ERB you can do some interesting things, like stop showing the announcement past a specified date:
 

develop/_sources/release-notes/v4.0-release-notes.rst.txt

@@ -40,6 +40,19 @@ whitelist & blacklist configs have been removed.
 
 .. include:: allowlist.inc
 
+Announcements are dismissable by default.
+*****************************************
+
+In 4.0 :ref:`configure_announcements` now have the ability to be ``dismissable``.
+Meaning users can press ``OK`` on the announment and it will no longer appear
+on the pages.
+
+In prior versions of Open OnDemand there was no way to dismiss or get rid of announcements.
+Now in version 4.0, not only is there a way to dismiss announcements, announcements
+themselves are ``dismissable`` by default.
+
+The documentation for :ref:`configure_announcements` has been updated with this new feature.
+
 Dependency updates
 ..................
 

develop/customizations.html

@@ -368,7 +368,7 @@
 </div>
 </div>
 <div class="section" id="announcements">
-<h2>Announcements<a class="headerlink" href="#announcements" title="Permalink to this headline">¶</a></h2>
+<span id="configure-announcements"></span><h2>Announcements<a class="headerlink" href="#announcements" title="Permalink to this headline">¶</a></h2>
 <p>To add an announcement message that appears at the top of the dashboard you can create a file at <code class="docutils literal notranslate"><span class="pre">/etc/ood/config/announcement.(md|yml)</span></code> or <code class="docutils literal notranslate"><span class="pre">/etc/ood/config/announcements.d/any_file_name.(md|yml)</span></code>.</p>
 <p>On each request the dashboard will check for the existence of this file. If it exists, the contents will be converted using markdown converter to HTML and displayed inside a bootstrap alert.</p>
 <p>For example, if I create an announcement.md file with the contents:</p>
@@ -386,23 +386,37 @@ <h2>Announcements<a class="headerlink" href="#announcements" title="Permalink to
 </div>
 <p>If the announcement file has the extension <code class="docutils literal notranslate"><span class="pre">yml</span></code> and is a yaml file it is first rendered using ERB and then the resulting file is parsed as YAML. The valid keys are:</p>
 <table class="docutils align-default" id="id24">
-<caption><span class="caption-number">Table 2 </span><span class="caption-text">Config Files</span><a class="headerlink" href="#id24" title="Permalink to this table">¶</a></caption>
+<caption><span class="caption-number">Table 2 </span><span class="caption-text">Announcement configuration keys.</span><a class="headerlink" href="#id24" title="Permalink to this table">¶</a></caption>
 <colgroup>
-<col style="width: 33%" />
-<col style="width: 33%" />
-<col style="width: 33%" />
+<col style="width: 50%" />
+<col style="width: 50%" />
 </colgroup>
 <tbody>
-<tr class="row-odd"><th class="stub"><p>type</p></th>
-<td><p>warning, info, success, or danger</p></td>
-<td><p>this is the Bootstrap alert style</p></td>
+<tr class="row-odd"><td><p>Key</p></td>
+<td><p>Description</p></td>
+</tr>
+<tr class="row-even"><td><p>type</p></td>
+<td><p>The type of announcment. Values can be <code class="docutils literal notranslate"><span class="pre">warning</span></code>, <code class="docutils literal notranslate"><span class="pre">info</span></code>, <code class="docutils literal notranslate"><span class="pre">success</span></code>, or <code class="docutils literal notranslate"><span class="pre">danger</span></code>.</p></td>
+</tr>
+<tr class="row-odd"><td><p>msg</p></td>
+<td><p>The announcement’s message.</p></td>
 </tr>
-<tr class="row-even"><th class="stub"><p>msg</p></th>
-<td><p>string containing markdown formatted message</p></td>
-<td><p>if this is a blank string (only whitespace), the alert will not display</p></td>
+<tr class="row-even"><td><p>dismissable</p></td>
+<td><p>Specify if the announcment is dismissable or not with <code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>.
+Defaults to <code class="docutils literal notranslate"><span class="pre">true</span></code>.</p></td>
+</tr>
+<tr class="row-odd"><td><p>required</p></td>
+<td><p>Specify if the announcment is required or not with <code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>.
+Defaults to <code class="docutils literal notranslate"><span class="pre">false</span></code>. When this is set to <code class="docutils literal notranslate"><span class="pre">true</span></code>, the user will not be
+do anything until the announcment has been accepted.</p></td>
 </tr>
 </tbody>
 </table>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>You can use <code class="docutils literal notranslate"><span class="pre">required</span></code> announcements to present users with a ToS (terms of service),
+EULA (end user license agreement) or similar.</p>
+</div>
 <p>Because the announcement is rendered via ERB you can do some interesting things, like stop showing the announcement past a specified date:</p>
 <blockquote>
 <div><div class="highlight-erb notranslate"><div class="highlight"><pre><span></span><span class="x">type: warning</span>

develop/release-notes/v4.0-release-notes.html

@@ -293,6 +293,16 @@ <h4>whitelist &amp; blacklist configs have been removed.<a class="headerlink" hr
 instead of <code class="docutils literal notranslate"><span class="pre">whitelist</span></code> and <code class="docutils literal notranslate"><span class="pre">blacklist</span></code>, though sites should just use
 Linux FACLs to control these files instead of these configurations.</p>
 </div>
+<div class="section" id="announcements-are-dismissable-by-default">
+<h4>Announcements are dismissable by default.<a class="headerlink" href="#announcements-are-dismissable-by-default" title="Permalink to this headline">¶</a></h4>
+<p>In 4.0 <a class="reference internal" href="../customizations.html#configure-announcements"><span class="std std-ref">Announcements</span></a> now have the ability to be <code class="docutils literal notranslate"><span class="pre">dismissable</span></code>.
+Meaning users can press <code class="docutils literal notranslate"><span class="pre">OK</span></code> on the announment and it will no longer appear
+on the pages.</p>
+<p>In prior versions of Open OnDemand there was no way to dismiss or get rid of announcements.
+Now in version 4.0, not only is there a way to dismiss announcements, announcements
+themselves are <code class="docutils literal notranslate"><span class="pre">dismissable</span></code> by default.</p>
+<p>The documentation for <a class="reference internal" href="../customizations.html#configure-announcements"><span class="std std-ref">Announcements</span></a> has been updated with this new feature.</p>
+</div>
 </div>
 <div class="section" id="dependency-updates">
 <h3>Dependency updates<a class="headerlink" href="#dependency-updates" title="Permalink to this headline">¶</a></h3>