Improve pygments.enabled discussion

Summary: Ref T6533. Provide better instructions around installing, enabling, and troubleshooting Pygments.

Test Plan: Read documentation, viewed config option, clicked links.

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley, fabe

Maniphest Tasks: T6533

Differential Revision: https://secure.phabricator.com/D11053

src/applications/config/option/PhabricatorSyntaxHighlightingConfigOptions.php

@@ -12,6 +12,9 @@ final class PhabricatorSyntaxHighlightingConfigOptions
   }
 
   public function getOptions() {
+
+    $caches_href = PhabricatorEnv::getDocLink('Managing Caches');
+
     return array(
       $this->newOption(
         'syntax-highlighter.engine',
@@ -27,13 +30,32 @@ final class PhabricatorSyntaxHighlightingConfigOptions
             'PhutilSyntaxHighlighterEngine.')),
       $this->newOption('pygments.enabled', 'bool', false)
         ->setSummary(
-          pht('Should Phabricator shell out to Pygments to highlight code?'))
+          pht('Should Phabricator use Pygments to highlight code?'))
+        ->setBoolOptions(
+          array(
+            pht('Use Pygments'),
+            pht('Do Not Use Pygments'),
+          ))
         ->setDescription(
           pht(
-            "If you want syntax highlighting for other languages than PHP ".
-            "then you can install the python package 'Pygments', make sure ".
-            "the 'pygmentize' script is  available in the \$PATH of the ".
-            "webserver, and then enable this.")),
+            'Phabricator supports syntax highlighting a few languages by '.
+            'default, but you can install Pygments (a third-party syntax '.
+            'highlighting tool) to provide support for many more languages.'.
+            "\n\n".
+            'To install Pygments, visit '.
+            '[[ http://pygments.org | pygments.org ]] and follow the '.
+            'download and install instructions.'.
+            "\n\n".
+            'Once Pygments is installed, enable this option '.
+            '(`pygments.enabled`) to make Phabricator use Pygments when '.
+            'highlighting source code.'.
+            "\n\n".
+            'After you install and enable Pygments, newly created source '.
+            'code (like diffs and pastes) should highlight correctly. '.
+            'You may need to clear Phabricator\'s caches to get previously '.
+            'existing source code to highlight. For instructions on '.
+            'managing caches, see [[ %s | Managing Caches ]].',
+            $caches_href)),
       $this->newOption(
         'pygments.dropdown-choices',
         'wild',

src/docs/user/configuration/managing_caches.diviner

@@ -0,0 +1,47 @@
+@title Managing Caches
+@group config
+
+Discusses Phabricator caches and cache management.
+
+Overview
+========
+
+Phabricator uses various caches to improve performance, similar to the caches
+a web browser uses to improve web performance.
+
+In particular, blocks of text which are expensive to render (like formatted
+text and syntax highlighted code) are often cached after they're rendered for
+the first time. When they're rendered again, Phabricator can read the cache
+instead of recomputing the result.
+
+Because text is cached, you may continue to see the old result even after you
+make certain configuration changes which should affect it. The most common
+example of this is that if you enable syntax highlighting with Pygments, old
+diffs and pastes may not appear highlighted.
+
+You may also run into this issue if you modify existing Remarkup rules or
+develop new ones, or modify other parts of the code that run before the results
+are cached.
+
+Caches will naturally expire over time, so if they aren't causing a problem
+you can just ignore the out of date caches and they'll fix themselves
+eventually (usually within 30 days).
+
+If you don't want to wait, you can purge the caches. This will remove any
+cached data and force Phabricator to recompute the results.
+
+Purging Caches
+==============
+
+If you need to purge Phabricator's caches, you can use the CLI tool. Run it
+with the `--help` flag to see options:
+
+  phabricator/ $ ./bin/cache purge --help
+
+This tool can purge caches in a granular way, but it's normally easiest to
+just purge all of the caches:
+
+  phabricator/ $ ./bin/cache purge --purge-all
+
+You can purge caches safely. The data they contain can always be rebuilt from
+other data if Phabricator needs it.