From 03056c720649671c27e1860a47817bccef65ade4 Mon Sep 17 00:00:00 2001 From: epriestley Date: Tue, 31 May 2011 12:14:20 -0700 Subject: [PATCH] Reorganize documentation. --- src/docs/arcconfig.diviner | 52 ------------ ...building_new_configuration_classes.diviner | 83 ------------------- src/docs/overview.diviner | 39 ++++----- src/docs/svn_hooks.diviner | 37 --------- 4 files changed, 16 insertions(+), 195 deletions(-) delete mode 100644 src/docs/arcconfig.diviner delete mode 100644 src/docs/building_new_configuration_classes.diviner delete mode 100644 src/docs/svn_hooks.diviner diff --git a/src/docs/arcconfig.diviner b/src/docs/arcconfig.diviner deleted file mode 100644 index 4ac19c9f..00000000 --- a/src/docs/arcconfig.diviner +++ /dev/null @@ -1,52 +0,0 @@ -@title Setting Up .arcconfig -@group config - -Explains how to configure Arcanist projects with ##.arcconfig## files. - -= .arcconfig Basics = - -Arcanist uses ##.arcconfig## files to determine a number of things about project -configuration. For instance, these are things it figures out from -##.arcconfig##: - - - where the logical root directory of a project is; - - which server Arcanist should send diffs to for code review; and - - which lint rules should be applied. - -An ##.arcconfig## file is a JSON file which you check into your project's root. -A simple, valid file looks something like this: - - { - "project_id" : "some_project_name", - "conduit_uri" : "https://phabricator.example.com/api/" - } - -Here's what these options mean: - - - **project_id**: a human-readable string identifying the project - - **conduit_uri**: the Conduit API URI for the Phabricator installation that - Arcanist should send diffs to for review. Generally, if you access - Phabricator at ##https://phabricator.example.com/##, the **conduit_uri** is - ##https://phabricator.example.com/api/##. Be mindful about "http" vs - "https". - -For an exhaustive list of available options, see below. - -= Advanced .arcconfig = - -Other options include: - - - **lint_engine**: the name of a subclass of @{class:ArcanistLintEngine}, - which should be used to apply lint rules to this project. See (TODO). - - **unit_engine**: the name of a subclass of - @{class:ArcanistBaseUnitTestEngine}, which should be used to apply unit - test rules to this project. See (TODO). - - **arcanist_configuration**: the name of a subclass of - @{class:ArcanistConfiguration} which can add new command flags for this - project or provide entirely new commands. - - **remote_hooks_installed**: tells Arcanist that you've set up remote hooks - in the master repository (see @{article:Installing Arcanist SVN Hooks} for - SVN, or (TODO) for git). - - **copyright_holder**: used by @{class:ArcanistLicenseLinter} to apply - license notices to source files. - - **phutil_libraries**: map of additional Phutil libraries to load at startup. diff --git a/src/docs/building_new_configuration_classes.diviner b/src/docs/building_new_configuration_classes.diviner deleted file mode 100644 index 6fb31617..00000000 --- a/src/docs/building_new_configuration_classes.diviner +++ /dev/null @@ -1,83 +0,0 @@ -@title Building New Configuration Classes -@group config - -Explains how to build new classes to control how Arcanist behaves. - -= Overview = - -Arcanist has some basic configuration options available in the ##.arcconfig## -file (see @{article:Setting Up .arcconfig}), but it can't handle everything. If -you want to customize Arcanist at a deeper level, you need to build new classes. -For instance: - - - if you want to configure linters, or add new linters, you need to create a - new class which extends @{class:ArcanistLintEngine}. - - if you want to integrate with a unit testing framework, you need to create a - new class which extends @{class:ArcanistBaseUnitTestEngine}. - - if you you want to change how workflows behave, or add new workflows, you - need to create a new class which extends @{class:ArcanistConfiguration}. - -Arcanist works through a sort of dependency-injection approach. For example, -Arcanist does not run lint rules by default, but you can set **lint_engine** -in your ##.arcconfig## to the name of a class which extends -@{class:ArcanistLintEngine}. When running from inside your project, Arcanist -will load this class and call methods on it in order to run lint. To make this -work, you need to do three things: - - - actually write the class; - - add the library where the class exists to your ##.arcconfig##; - - add the class name to your ##.arcconfig## as the **lint_engine**, - **unit_engine**, or **arcanist_configuration**. - -= Write the Class = - -(TODO) - -= Load the Class = - -To make the class loadable, you need to put the path to it in your -##.arcconfig##, under **phutil_libraries**: - - { - // ... - "phutil_libraries" : { - // ... - "my-library" : "/path/to/my/library", - // ... - } - // ... - } - -You can either specify an absolute path, or a path relative to the project root. -When you run ##arc --trace##, you should see a message to the effect that it has -loaded your library. - -For debugging or testing, you can also run Arcanist with the -##--load-phutil-library## flag: - - arc --load-phutil-library=/path/to/library - -You can specify this flag more than once to load several libraries. Note that -if you use this flag, Arcanist will ignore any libraries listed in -##.arcconfig##. - -= Use the Class = - -This step is easy: just edit ##.arcconfig## to specify your class name as -the appropriate configuration value. - - { - // ... - "lint_engine" : "MyCustomArcanistLintEngine", - // ... - } - -Now, when you run Arcanist in your project, it will invoke your class when -appropriate. - -For lint and unit tests, you can also use the ##--engine## flag override the -default engine: - - arc lint --engine MyCustomArcanistLintEngine - -This is mostly useful for debugging and testing. diff --git a/src/docs/overview.diviner b/src/docs/overview.diviner index f785ad97..07e2cd33 100644 --- a/src/docs/overview.diviner +++ b/src/docs/overview.diviner @@ -3,29 +3,22 @@ Overview of Arcanist, a code workflow tool. -Arcanist (commonly, "arc") is the command-line frontend to Differential. A -detailed command reference is available by running ##arc help##. +Arcanist (commonly, "arc") is the command-line frontend to Phabricator and +Differential. A detailed command reference is available by running ##arc help##. -= Overview = += Documentation = -Arcanist is the command-line interface to Differential, and supports some -related revision control operations. Arcanist allows you to do things like: - - - send your code to Differential for review with ##arc diff## - - commit reviewed changes with ##arc commit## (svn) or ##arc amend## (git) - - check your code for syntax and style errors with ##arc lint## - - run unit tests that cover your changes with ##arc unit## - - export changes from Differential or the working copy with ##arc export## - - apply patches from Differential or patchfiles with ##arc patch## - - execute context-aware blame with ##arc cover## - - show Differential status with ##arc list## - -In general, these workflows are agnostic to the underlying version control -system and will work properly in git or svn repositories. - -= Configuring a New Project = - -Create a .arcconfig file. - -= SVN Basics = +The Arcanist documentation is primarily focused at Arcanist developers and +explains the project's internals. Arcanist user documentation which explains +how to use the tool is available in the Phabricator project: + - for an overview of Arcanist, see @{article@phabricator:Arcanist User + Guide}. + - for information on configuring a new project and setting up an + ##.arcconfig## file, see @{article@phabricator:Arcanist User Guide: + Configuring a New Project}. + - to install remote hooks in a repository, see @{article@phabricator:Arcanist + User Guide: Repository Hooks}. + - to integrate Arcanist with linters, unit tests and custom workflows, see + @{article@phabricator:Arcanist User Guide: Customizing Lint, Unit Tests and + Workflows}. \ No newline at end of file diff --git a/src/docs/svn_hooks.diviner b/src/docs/svn_hooks.diviner deleted file mode 100644 index 27c4d908..00000000 --- a/src/docs/svn_hooks.diviner +++ /dev/null @@ -1,37 +0,0 @@ -@title Installing Arcanist SVN Hooks -@group config - -Describes how to set up Arcanist as an SVN pre-commit hook. - -= Installing Arcanist SVN Hooks = - -You can install Arcanist as an SVN pre-commit hook, to reject commits which -contain lint errors. The immediate value of this is that syntax errors won't -be committable, but you can block other kinds of badness with appropriate lint -engines. - -To install Arcanist as a pre-commit hook, add this to your svn/hooks/pre-commit: - - #!/bin/sh - /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit $@ 1>&2 - -Make sure you make this file executable, or you'll get an error for every commit -with an unhelpful error message. You also need to specify the full path to PHP -since SVN nukes ENV before executing scripts. Alternatively you can specify -PATH explicitly. - -If your project is configured to run linters or lint engines which aren't part -of Arcanist, specify where to load them from with ##--load-phutil-library##: - - --load-phutil-library=/path/to/library/root - -Since SVN commit hooks run without access to a working copy, you'll need to keep -one checked out somewhere and reference it with ##--load-phutil-library## if you -build new linters or customize lint engines. For example, your hook might -look like this: - - #!/bin/sh - /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit \ - --load-phutil-library=/path/to/custom/lint/engine \ - --load-phutil-library=/path/to/custom/unittest/engine \ - $@ 1>&2