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/arcanist_lint_unit.diviner

@@ -30,38 +30,11 @@ make this work, you need to do three things:
   - add the class name to your ##.arcconfig## as the **lint_engine**,
     **unit_engine**, or **arcanist_configuration**.
 
-= Write the Class =
+= Create a libphutil Library =
 
-Start by creating a new phutil library -- this is a directory which will contain
-class files for Arcanist to load. You can either put it inside your project, or
-outside (if you want to share lint rules between several projects, for
-instance). To create a new library, run ##arc liberate##:
-
-  $ arc liberate path/to/new/library
-
-This will prompt you to name your library and create a new directory on disk.
-Create a new ##lint/## directory in this library (or ##unit/##, or whatever you
-want). This creates a module. Put ##CustomArcanistLintEngine.php## inside the
-##lint/## directory:
-
-  lang=php
-  <?php
-
-  class CustomArcanistLintEngine extends ArcanistLintEngine {
-
-  }
-
-Now run ##arc liberate## on the library again. Whenever you add, remove, or
-rename modules or classes you should run ##arc liberate## to update the
-classmap.
-
-You can either write the class body now (refer to the documentation for the
-class you are extending) or continue with integrating it into your project.
-
-= Load the Class =
-
-To make the class loadable, you need to put the path to it in your
-##.arcconfig##, under **phutil_libraries**:
+If you haven't created a library for the class to live in yet, you need to do
+that first. Follow the instructions in @{article:libphutil Library User Guide},
+then make the library loadable by adding it to your ##.arcconfig## like this:
 
   {
     // ...

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.