Repository: translate/pootle

Issue:
Point superusers to docs in persistent flashing "stats are calculating" banner
Despite that fact that right now on `master` the [persistent flashing  #banner](https://github.com/translate/pootle/blob/95f17ca4/pootle/templates/browser/index.html#L145-L151) doesn't show up often.  A lot of people had, and most likely still have, problems to find the docs with the tips on how to fix the situation.

So we need to:
1. Provide a link pointing to the docs for site admins (superusers)
2. Remove the cycling component. If the admin is unable to fix the issue quickly we shouldn't harass anyone.

Also it is not a bad idea to review such docs http://docs.translatehouse.org/projects/pootle/en/latest/server/rq.html to make sure they:
- Are easy to understand
- Provide enough hints on debugging the underlying issues
- Provide simple ways to fix the known issues (like perhaps use `flush_cache` instead of Redis commands)
- Backport the docs to 2.7.x branch (or at least the part that applies)
- Encourage reporting of the issues to GitHub



Discussion:
@julen suggested some ideas:
- Try to determine if it failed (there should be no pending jobs) to display to admins it failed (instead of relying on "If it takes too much time it might have failed, so check this docs")
- Hide the banner after a given amount of time if it can't be determined if it failed to complete (for regular users)

@iafan Do you have any input?

> Remove the cycling component. If the admin is unable to fix the issue quickly we shouldn't harass anyone.

I think we still want to communicate the fact that the stats are outdated. If we simply hide the entire notice, this will mean that people will start bumping into situations where they click somewhere an get no results, or results are different, and the system will behave as a broken one, but now without any clear indication what was the reason of this behavior in the first place.

Speaking of the visual countdown component, I think there's a room for improvement. My feeling is that what irritates people most is that countdown thing that never ends in case the job has failed or workers are not running. If we could determine that the system is in a bad state, and the stats aren't going to be updated anytime soon, we'd rather:
1. notify administrators by email and in the dashboard
2. show a different static message to non-admins and do no reload attempts. Something like: "Statistics on this page are outdated. Administrators have already been notified of this problem".

> Hide the banner after a given amount of time

I didn't suggest this, in fact the opposite: the banner should never be hidden if stats are not up-to-date. You probably misunderstood when I was referring to hiding the counter/refresh behavior and adjusting the message accordingly. Note however there needs to be a reliable way to determine brokenness in the first place.


Resolving patch:
diff --git a/pootle/core/templatetags/core.py b/pootle/core/templatetags/core.py
--- a/pootle/core/templatetags/core.py
+++ b/pootle/core/templatetags/core.py
@@ -11,6 +11,7 @@
 from django.utils.html import escapejs
 from django.utils.safestring import mark_safe
 
+from ..utils.docs import get_docs_url
 from ..utils.json import jsonify
 
 
@@ -23,3 +24,9 @@ def to_js(value):
     consumption.
     """
     return mark_safe('JSON.parse("%s")' % escapejs(jsonify(value)))
+
+
+@register.filter
+def docs_url(path_name):
+    """Returns the absolute URL to `path_name` in the RTD docs."""
+    return get_docs_url(path_name)
diff --git a/pootle/core/views.py b/pootle/core/views.py
--- a/pootle/core/views.py
+++ b/pootle/core/views.py
@@ -656,6 +656,8 @@ def get_context_data(self, *args, **kwargs):
 
         ctx.update(
             {'page': 'browse',
+             'stats_refresh_attempts_count':
+                 settings.POOTLE_STATS_REFRESH_ATTEMPTS_COUNT,
              'stats': self.stats,
              'translation_states': get_translation_states(self.object),
              'checks': get_qualitycheck_list(self.object),


Test patch: