Improve documentation around creating extension libraries for Phabricator

Summary: There was some documentation for this but it was kind of buried in a
random, difficult-to-discover file. Separate it into its own file and link to it
from the previous location.

Test Plan: Regenerated documentation and read through it without catching
anything terrible.

Reviewers: btrahan

Reviewed By: btrahan

CC: zeeg, aran, btrahan

Maniphest Tasks: T643

Differential Revision: 1161

src/docs/userguide/libraries.diviner

@@ -0,0 +1,124 @@
+@title libphutil Libraries User Guide
+@group userguide
+
+Guide to creating and managing libphutil libraries.
+
+= Overview =
+
+libphutil includes a library system which organizes PHP classes and functions
+into modules. Some extensions and customizations of Arcanist and Phabricator
+require you to make code available to Phabricator by providing it in a libphutil
+library.
+
+For example, if you want to store files in some kind of custom storage engine,
+you need to write a class which can interact with that engine and then tell
+Phabricator to load it.
+
+In general, you perform these one-time setup steps:
+
+  - Create a new directory.
+  - Use ##arc liberate## to initialize and name the library.
+  - Add a dependency on Phabricator if necessary.
+  - Add the library to your Phabricator config or ##.arcconfig## so it will be
+    loaded at runtime.
+
+Then, to add new code, you do this:
+
+  - Write or update classes.
+  - Update the library metadata by running ##arc liberate## again.
+
+= Creating a New Library =
+
+To **create a new libphutil library**:
+
+  $ mkdir libcustom/
+  $ cd libcustom/
+  libcustom/ $ arc liberate src/
+
+Now you'll get a prompt like this:
+
+  No library currently exists at that path...
+  The directory '/some/path/libcustom/src' does not exist.
+
+    Do you want to create it? [y/N] y
+  Creating new libphutil library in '/some/path/libcustom/src'.
+  Choose a name for the new library.
+
+    What do you want to name this library?
+
+Choose a library name (in this case, "libcustom" would be appropriate) and it
+you should get some details about the library initialization:
+
+  Writing '__phutil_library_init__.php' to
+    '/some/path/libcustom/src/__phutil_library_init__.php'...
+  Using library root at 'src'...
+  Mapping library...
+  Verifying library...
+  Finalizing library map...
+    OKAY   Library updated.
+
+This will write three files:
+
+  - ##src/.phutil_module_cache## This is a cache which makes "arc liberate"
+    faster when you run it to update the library. You can safely remove it at
+    any time. If you check your library into version control, you can add this
+    file to ignore rules (like .gitignore).
+  - ##src/__phutil_library_init__.php## This records the name of the library and
+    tells libphutil that a library exists here.
+  - ##src/__phutil_library_map__.php## This is a map of all the symbols
+    (functions and classes) in the library, which allows them to be autoloaded
+    at runtime and dependencies to be statically managed by "arc liberate".
+
+= Linking with Phabricator =
+
+If you aren't using this library with Phabricator (e.g., you are only using it
+with Arcanist or are building something else on libphutil) you can skip this
+step.
+
+But, if you intend to use this library with Phabricator, you need to define its
+dependency on Phabricator by creating a ##.arcconfig## file which points at
+Phabricator. For example, you might write this file to
+##libcustom/.arcconfig##:
+
+  {
+    "project_id" : "libcustom",
+    "phutil_libraries" : {
+      "phabricator" : "phabricator/src/"
+    }
+  }
+
+For details on creating a ##.arcconfig##, see
+@{article:Arcanist User Guide: Configuring a New Project}. In general, this
+tells ##arc liberate## that it should look for symbols in Phabricator when
+performing static analysis.
+
+NOTE: If Phabricator isn't located next to your custom library, specify a
+path which actually points to the ##phabricator/## directory.
+
+You do not need to declare dependencies on ##arcanist## or ##libphutil##,
+since ##arc liberate## automatically loads them.
+
+Finally, edit your Phabricator config to tell it to load your library at
+runtime, by adding it to ##load-libraries##:
+
+  ...
+  'load-libraries' => array(
+    'libcustom' => 'libcustom/src/',
+  ),
+  ...
+
+Now, Phabricator will be able to load classes from your custom library.
+
+= Writing Classes =
+
+To actually write classes, create a new module and put code in it:
+
+  libcustom/ $ mkdir src/example/
+  libcustom/ $ nano src/example/ExampleClass.php # Edit some code.
+
+Now, run ##arc liberate## to regenerate the static resource map:
+
+  libcustom/ $ arc liberate src/
+
+This will automatically create and update ##__init__.php## files, and regenerate
+the static map of the library.