Basic doc for adding/updating Celerity CSS/JS.

Summary:

Test Plan:

Reviewers:

CC:

.divinerconfig

@@ -6,7 +6,7 @@
     "install" : "Installing",
     "config" : "Configuration",
     "userguide" : "Application User Guides",
-
+    "developer" : "Phabricator Developer Guides",
     "differential" : "Differential (Code Review)",
     "diffusion" : "Diffusion (Repository Browser)",
     "maniphest" : "Maniphest (Task Tracking)",

src/docs/adding_new_css_and_js.diviner

@@ -0,0 +1,77 @@
+@title Adding New CSS and JS
+@group developer
+
+Explains how to add new CSS and JS files to Phabricator.
+
+= Overview =
+
+Phabricator uses a system called **Celerity** to manage static resources. If you
+are a current or former Facebook employee, Celerity is based on the Haste system
+used at Facebook and generally behaves similarly.
+
+= Adding a New File =
+
+To add a new CSS or JS file, create it in an appropriate location in
+##webroot/rsrc/css/## or ##webroot/rsrc/js/## inside your ##phabricator/##
+directory.
+
+Each file must ##@provides## itself as a component, declared in a header
+comment:
+
+  LANG=css
+  /**
+   * @provides duck-styles-css
+   */
+
+  .duck-header {
+    font-size: 9001px;
+  }
+
+Note that this comment must be a Javadoc-style comment, not just any comment.
+
+If your component depends on other components (which is common in JS but
+rare and inadvisable in CSS), declare then with ##@requires##:
+
+  LANG=js
+  /**
+   * @requires javelin-stratcom
+   * @provides duck
+   */
+
+  /**
+   * Put class documentation here, NOT in the header block.
+   */
+  JX.install('Duck', {
+    ...
+  });
+  
+Then rebuild the Celerity map (see the next section).
+
+= Changing an Existing File =
+
+When you add, move or remove a file, or change the contents of existing JS or
+CSS file, you should rebuild the Celerity map:
+
+  phabricator/ $ ./scripts/celerity_mapper.php ./webroot
+  
+If you've only changed file content things will generally work even if you
+don't, but they might start not working as well in the future if you skip this
+step.
+
+= Including a File =
+
+To include a CSS or JS file in a page, use
+@{function:require_celerity_resource}:
+
+  require_celerity_resource('duck-style-css');
+  require_celerity_resource('duck');
+  
+If your map is up to date, the resource should now be included correctly when
+the page is rendered.
+
+You should place this call as close to the code which actually uses the resource
+as possible, i.e. **not** at the top of your Controller. The idea is that you
+should @{function:require_celerity_resource} a resource only if you are actually
+using it on a specific rendering of the page, not just because some views of the
+page might require it.
+