Allow Diviner books to have a "preface" section

Summary: Ref T988. This is primarily intended to let us add the "HEY! THIS ISN'T USER DOCUMENTATION" notices to the arcanist and libphutil technical docs.

Test Plan: Added some prefaces, generated docs, looked at them.

Reviewers: chad, btrahan

Reviewed By: btrahan

CC: aran

Maniphest Tasks: T988

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

resources/celerity/map.php

@@ -401,7 +401,7 @@ return array(
     'rsrc/js/application/policy/behavior-policy-control.js' => 'c01153ea',
     'rsrc/js/application/policy/behavior-policy-rule-editor.js' => '263aeb8c',
     'rsrc/js/application/ponder/behavior-votebox.js' => '327dbe61',
-    'rsrc/js/application/projects/behavior-project-boards.js' => '1b9facd8',
+    'rsrc/js/application/projects/behavior-project-boards.js' => 'cbdc9b22',
     'rsrc/js/application/projects/behavior-project-create.js' => '065227cc',
     'rsrc/js/application/releeph/releeph-preview-branch.js' => '9eb2cedb',
     'rsrc/js/application/releeph/releeph-request-state-change.js' => 'fe7fc914',
@@ -610,7 +610,7 @@ return array(
     'javelin-behavior-policy-control' => 'c01153ea',
     'javelin-behavior-policy-rule-editor' => '263aeb8c',
     'javelin-behavior-ponder-votebox' => '327dbe61',
-    'javelin-behavior-project-boards' => '1b9facd8',
+    'javelin-behavior-project-boards' => 'cbdc9b22',
     'javelin-behavior-project-create' => '065227cc',
     'javelin-behavior-refresh-csrf' => 'c4b31646',
     'javelin-behavior-releeph-preview-branch' => '9eb2cedb',
@@ -937,15 +937,6 @@ return array(
       1 => 'javelin-util',
       2 => 'phabricator-keyboard-shortcut-manager',
     ),
-    '1b9facd8' =>
-    array(
-      0 => 'javelin-behavior',
-      1 => 'javelin-dom',
-      2 => 'javelin-util',
-      3 => 'javelin-stratcom',
-      4 => 'javelin-workflow',
-      5 => 'phabricator-draggable-list',
-    ),
     '1e1c8a59' =>
     array(
       0 => 'javelin-behavior',
@@ -1225,13 +1216,6 @@ return array(
       2 => 'javelin-util',
       3 => 'phabricator-shaped-request',
     ),
-    '62e18640' =>
-    array(
-      0 => 'javelin-install',
-      1 => 'javelin-util',
-      2 => 'javelin-dom',
-      3 => 'javelin-typeahead-normalizer',
-    ),
     '6453c869' =>
     array(
       0 => 'javelin-install',
@@ -1265,6 +1249,13 @@ return array(
       0 => 'javelin-behavior',
       1 => 'javelin-dom',
     ),
+    '62e18640' =>
+    array(
+      0 => 'javelin-install',
+      1 => 'javelin-util',
+      2 => 'javelin-dom',
+      3 => 'javelin-typeahead-normalizer',
+    ),
     '75903ee1' =>
     array(
       0 => 'javelin-behavior',
@@ -1698,6 +1689,15 @@ return array(
       2 => 'javelin-stratcom',
       3 => 'phabricator-phtize',
     ),
+    'cbdc9b22' =>
+    array(
+      0 => 'javelin-behavior',
+      1 => 'javelin-dom',
+      2 => 'javelin-util',
+      3 => 'javelin-stratcom',
+      4 => 'javelin-workflow',
+      5 => 'phabricator-draggable-list',
+    ),
     'cd9e7094' =>
     array(
       0 => 'javelin-behavior',

src/applications/diviner/controller/DivinerBookController.php

@@ -83,17 +83,26 @@ final class DivinerBookController extends DivinerController {
   }
 
   private function buildPropertyList(DivinerLiveBook $book) {
-    $user = $this->getRequest()->getUser();
+    $viewer = $this->getRequest()->getUser();
     $view = id(new PHUIPropertyListView())
-      ->setUser($user);
+      ->setUser($viewer);
 
     $policies = PhabricatorPolicyQuery::renderPolicyDescriptions(
-      $user,
+      $viewer,
       $book);
 
     $view->addProperty(
       pht('Updated'),
-      phabricator_datetime($book->getDateModified(), $user));
+      phabricator_datetime($book->getDateModified(), $viewer));
+
+    $preface = $book->getPreface();
+    if (strlen($preface)) {
+      $view->addTextContent(
+        PhabricatorMarkupEngine::renderOneObject(
+          id(new PhabricatorMarkupOneOff())->setContent($preface),
+          'default',
+          $viewer));
+    }
 
     return $view;
   }

src/applications/diviner/storage/DivinerLiveBook.php

@@ -38,6 +38,10 @@ final class DivinerLiveBook extends DivinerDAO
     return $this->getConfig('short', $this->getTitle());
   }
 
+  public function getPreface() {
+    return $this->getConfig('preface');
+  }
+
   public function getGroupName($group) {
     $groups = $this->getConfig('groups');
     $spec = idx($groups, $group, array());

src/applications/diviner/workflow/DivinerWorkflow.php

@@ -37,6 +37,7 @@ abstract class DivinerWorkflow extends PhabricatorManagementWorkflow {
         'name' => 'string',
         'title' => 'optional string',
         'short' => 'optional string',
+        'preface' => 'optional string',
         'root' => 'optional string',
         'uri.source' => 'optional string',
         'rules' => 'optional map<regex, string>',

src/docs/book/phabricator.book

@@ -2,6 +2,7 @@
   "name" : "phabdev",
   "title" : "Phabricator Technical Documentation",
   "short" : "Phabricator Tech Docs",
+  "preface" : "Technical documentation intended for Phabricator developers.",
   "root" : "../../../",
   "uri.source" :
     "https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",

src/docs/book/user.book

@@ -2,6 +2,7 @@
   "name" : "phabricator",
   "title" : "Phabricator User Documentation",
   "short" : "Phabricator User Docs",
+  "preface" : "Instructions for installing, configuring, and using Phabricator.",
   "root" : "../../../",
   "uri.source" :
     "https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",