Merge pull request #4 from civicrm/master

merge from core

README.md

-# CiviCRM developer documentation
+# CiviCRM Developer Guide
 
-```bash
-git clone https://github.com/civicrm/civicrm-dev-docs
-cd civicrm-dev-docs
-mkdocs serve
-```
+-   [Read published version](http://docs.civicrm.org/dev/en/master)
+-   [Learn how to edit](https://docs.civicrm.org/dev/en/master/documentation/#how-to-edit)
 
-This will likely be merged with the `civicrm-core` repo at some point.
-
-# See also
+This Developer Guide will likely be merged into the
+[civicrm-core](https://github.com/civicrm/civicrm-core/) repo at some point.
\ No newline at end of file
-
- * Download mkdocs: http://mkdocs.org/
- * Browse published dev docs: http://docs.civicrm.org/dev/en/master
- * Review general info about CiviCRM docs: https://github.com/civicrm/civicrm-docs

docs/extensions/advanced.md

+# Advanced patterns
+
+[]( FIXME remove this banner after review)
+>> NOTE: Some of these instruction maybe deprecated and superceded by better
+>> approaches.
+
+## Web Services
+
+There are three options to create an ajax or web-service callback:
+
+-   **Full control:**Add a basic page. Remove the parent::run() call
+    from the run() function, and at the bottom of the run() function,
+    perform your own output (eg "*echo json\_encode($data)*") and then
+    short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so
+    that neither Smarty nor the CMS modify the output.
+-   **Using ajax helpers (CiviCRM 4.5 and above**): Generate a page with
+    civix as above. Build your data in the run() function. If the
+    client-side request includes *snippet=json* in the url, just append
+    your data to *$this-\>ajaxResponse* array and the rest will happen
+    automatically. If not, you can directly call
+    CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run
+    function. See [Ajax Pages and
+    Forms](/confluence/display/CRMDOC/Ajax+Pages+and+Forms)
+    documentation.
+-   **Using the API:** Add an API function using `civix`.
+    The API function can be called with the API's [AJAX
+    Interface](http://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
+    This automatically handles issues like encoding and decoding the
+    request/response.
+
+## Standalone PHP scripts
+
+Instead of creating a standalone script, consider one of these options:
+
+-   Add an API function (using the instructions above). The API function
+    can be called many different ways – cv, PHP, REST, AJAX, CLI, Drush,
+    Smarty, cron, etc. CiviCRM used to include a number of standalone
+    scripts – many of these have been migrated to API functions because
+    this approach is simpler and more flexible.
+-   Add a basic page (using the instructions above). At the bottom of
+    the run() function, call "*CRM\_Utils\_System::civiExit()*" to
+    short-circuit theming and CMS processing.
+
+Creating a pure standalone PHP script is a tricky proposition and likely to be
+brittle compared with the above.
+
+If the script is truly standalone and
+does not require any services from the CRM or CMS, then you can just add a
+new `.php` file to the extension... but it won't have access to CiviCRM's
+APIs, databases, classes, etc. If the standalone script needs those
+services, then it will need to ***bootstrap*** CiviCRM and the CMS. This
+is challenging for several reasons:
+
+-   The bootstrap mechanics are different in each CMS (Drupal, Joomla,
+    etc).
+-   The bootstrap mechanics are different for single-site installations
+    and multi-site installations
+-   To initiate a bootstrap from a script, one needs to determine the
+    local-path to the CiviCRM settings. However, the local-path of the
+    script is entirely independent of the local-path to the settings –
+    these are determined at the discretion of the site administrator.
+
+If you really need to do it, it's theoretically possibly to emulate an
+example like
+"[bin/deprecated/EmailProcessor.php](http://svn.civicrm.org/civicrm/branches/v4.1/bin/deprecated/EmailProcessor.php)".
+The results will likely be difficult for downstream users to
+install/use.
+
+
+## Cron jobs
+
+One can add an API function (using the instructions above) and create a
+schedule record. In CiviCRM 4.3, the schedule record can be
+automatically created; to do this, call "civix
+[generate:api](http://generateapi)" with the option "–schedule Daily"
+(or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet
+the stated schedule.
+
+In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record
+won't be created automatically. The site administrator must manually
+insert a scheduling record by navigating to "Administer =\> System
+Settings =\> Scheduled Jobs".
+

docs/extensions/basics.md

@@ -14,8 +14,41 @@ This section covers how to write extensions. See the [extension life cycle
 page](/extend-stages) for background on the publishing and review process for
 [published extensions](https://civicrm.org/extensions).
 
+## Extension Names
+
+All extension names follow the same convention as Java package names – they
+look like reversed domain names. (e.g.  `com.example.myextension`). For
+module-extensions, the last word in the module name will be the module's
+*short-name*. The short-name *must* be unique. It is possible to pick a
+different short-name, but that requires extra work.
+
+## Pre-Requisites
+
+-   Have basic knowledge of PHP, Unix, and object-oriented programming
+-   Install ***civix v14.01*** or newer. For instructions, see
+    [https://github.com/totten/civix/](https://github.com/totten/civix/)
+    . This wiki page assumes that "civix" is installed and registered in
+    the PATH.
+-   Configure an extensions directory. For instructions, see
+    [Extensions](http://wiki.civicrm.org/confluence/display/CRMDOC/Extensions).
+    This wiki page assumes the directory is "/var/www/extensions", but
+    you should adapt as appropriate.
+     Your extensions directory must be under the CMS root directory so
+    that civix can find and bootstrap the CMS. Otherwise, it will fail
+    with an error like "Sorry, could not locate bootstrap.inc" on most
+    operations.
+-   The user account you use to develop the module must have permission
+    to read all CMS files, including configuration files, and write to
+    the extensions directory.
+     For example, Debian's drupal7 package saves database configuration
+    to /etc/drupal/7/sites/default/dbconfig.php, which is only readable
+    by the www-data user. You will need to make this file readable by
+    your development user account for civix to work.
+
 ## General overview
 
+[]( fixme paragraph this section into above notes )
+
 If you haven't already, you need to configure a local directory to store
 extensions.
 For instructions, see

docs/extensions/files.md

-Coming soon!
+# Extension files
+
+The [civix](./civix) command line tool will generate the following structure
+for you:
+
+-   ***info.xml*** is a manifest that describes your extension – the
+    name, license, version number, etc. You should edit most information
+    in this file.
+-   ***myextension.php*** stores source code for all your hooks. It
+    includes a few default hook implementations which will make
+    development easier. You can add and remove hooks as you wish. (Note:
+    This file name is different in each module – it is based the
+    module's *[short-name](./basics/#extension-names)*.)
+-   ***myextension.civix.php*** contains auto-generated helper
+    functions. These deal with common problems like registering your
+    module in the template include-path. `civix` may automatically
+    overwrite this file, so generally do not edit it.
+
+In addition, it creates some empty directories. These directories are
+reminiscent of the directory structure in CiviCRM core:
+
+-   ***CRM/Myextension/*** stores PHP class files. Classes in this
+    folder should be prefixed with "CRM\_Myextension\_"
+-   ***templates/*** stores Smarty templates
+-   ***xml/*** stores XML configuration files (such as URL routes)
+-   ***build/*** stores exportable .zip files

docs/extensions/troubleshooting.md

+# Troubleshooting
+
+If you are struggling, the best thing to do is reach out to the
+[CiviCRM community](../basics/community).
+
+If you cannot find the answer in this guide or by searching in the
+[CiviCRM StackExchange site](http://civicrm.stackexchange.com/)
+then please [ask](http://civicrm.stackexchange.com/questions/ask). Asking
+questions on StackExchange not only helps you but may well help others who
+follow you.
+
+That said, this is a small list of some of the commoner problems extension
+writers encounter.
+
+## Extension not doing anything
+
+[]( ###### arguably this list should be removed altogether?? #### )
+
+Q: I've created the files and edited them but I don't see the expected
+changes.
+
+A: Did you install and enable your extension?
+(<site\>/civicrm/admin/extensions?reset=1)
+
+## Civix error messages
+
+Q: I get Error: "Cannot instantiate API client -- please set connection
+options in parameters.yml"
+
+A: You might have missed the step about setting
+'civicrm\_api3\_conf\_path'
+([https://github.com/totten/civix/](https://github.com/totten/civix/)),
+or it didn't get set properly for some reason.
+
+Q: I've tried to generate a page/report/search/upgrader/etc with civix
+but it's not working.
+
+A: For all of the various types, you must first run
+[generate:module](http://generatemodule), and then \`cd\` into the
+folder (e.g. com.example.myextension) before running one of the
+other \`generate:\` commands.
+

docs/index.md

 # CiviCRM Developer Guide
 
+!!! warning "Notice"
+    This guide is not yet complete.
+    As of early 2017 we are actively working to migrate content in from the
+    [wiki]. Read more about this [migration process][migration], including how
+    to help out!
+
+[wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
+[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
+
+
 [CiviCRM](https://civicrm.org) is an open-source application. The code can be
 poked, prodded, twisted, and hacked. It can be customized, extended, and
 collaboratively developed. This documentation tells you how to do that.
@@ -23,39 +33,4 @@ for use by people that are familiar with CiviCRM development.
     for specific details on editing this documentation (and others using
     mkdocs). You can also learn how to read these docs off-line!
 
-## Migration of content is in progress
-
-As of early 2017 we are actively working to migrate content from the [wiki] to
-this guide. Read more about this [migration process][migration], including how
-to help out!
-
-[wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
-[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
-
-## Other sources of information
-
-As an open-source project, CiviCRM is managed by an international community of
-developers and activists. Help from these people can be found in the following
-ways:
-
--   Our [chat rooms](https://chat.civicrm.org/) and
-    [mailing lists](http://lists.civicrm.org/lists/info/civicrm-dev) are great
-    places to say hello and discuss CiviCRM issues with others.
-
--   If you need help, your best bet is probably our
-    [stack exchange Q+A site](http://civicrm.stackexchange.com/).
-
--   If you've identified a problem, you can file issues on our
-    [issue](http://issues.civicrm.org/) on our issue tracker or fix the issue
-    and submit a pull request on
-    [Github](https://github.com/civicrm/civicrm-core/).
-
--   If you've written an extension, please share it in our
-    [extensions directory](https://civicrm.org).
-
--   Use the [wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki)
-    to share drafts, notes, and specs.
 
--   And don't forget you are always welcome to come to a
-    [real world event](https://civicrm.org/events) like a conference meet-up
-    or sprint.

docs/js/custom.js

+$(function() {
+
+  // Automatically scroll the navigation menu to the active element
+  //   https://github.com/civicrm/civicrm-dev-docs/issues/21
+  $.fn.isFullyWithinViewport = function(){
+      var viewport = {};
+      viewport.top = $(window).scrollTop();
+      viewport.bottom = viewport.top + $(window).height();
+      var bounds = {};
+      bounds.top = this.offset().top;
+      bounds.bottom = bounds.top + this.outerHeight();
+      return ( ! (
+        (bounds.top <= viewport.top) ||
+        (bounds.bottom >= viewport.bottom)
+      ) );
+  };
+  if( !$('li.toctree-l1.current').isFullyWithinViewport() ) {
+    $('.wy-nav-side')
+      .scrollTop(
+        $('li.toctree-l1.current').offset().top -
+        $('.wy-nav-side').offset().top -
+        60
+      );
+  }
+
+});

docs/markdownrules.md

@@ -32,10 +32,17 @@ platforms.
 
 ## Hyperlinks
 
--   A basic hyperlink
+-   A basic hyperlink (in a sentence)
 
         Try [CiviCRM](https://civicrm.org) for your database.
 
+-   An internal hyperlink on mkdocs (4 different ways that all work)
+
+        [extensions](/extensions/basics)
+        [extensions](/extensions/basics.md)
+        [extensions](extensions/basics)
+        [extensions](extensions/basics.md)
+
 -   With long URLs, the following syntax is better.
 
         See [this issue][CRM-19799] for more details.
@@ -85,7 +92,10 @@ This is a second.
 #### Heading 4
 ```
 
-Alternate syntax (only works for h1 and h2):
+The above syntax is [called](http://pandoc.org/MANUAL.html#headers)
+"ATX style headers" in markdown terminology, and is preferred my most.
+An alternate syntax called "setext style headers" works for h1 and h2 as
+follows:
 
 ```md
 Heading 1
@@ -272,7 +282,43 @@ mkdocs**:
 -   More list items
 ````
 
+## Admonitions
+
+### Types
+
+!!! note
+    I am a "note" admonition.
+
+!!! tip
+    I am a "tip" admonition.
+
+!!! warning
+    I am a "warning" admonition.
+
+!!! danger
+    I am a "danger" admonition.
+
+Other types
+
+-   "hint", "important" (visually identical to "tip")
+-   "attention", "caution" (visually identical to "warning")
+-   "error" (visually identical to "danger")
 
+### Syntax
+
+Simple example:
+
+```md
+!!! note
+    This feature is only available as of CiviCRM 4.5.
+```
+
+Add a custom title (make sure to quote the title):
+
+```md
+!!! danger "Don't try this at home!"
+    Stand back. I'm about to try science!
+```
 
 ## Images
 

mkdocs.yml

@@ -3,6 +3,10 @@ repo_url: https://github.com/civicrm/civicrm-dev-docs
 site_description: A guide for CiviCRM developers.
 site_author: The CiviCRM community
 theme: readthedocs
+extra_javascript:
+  - js/custom.js
+markdown_extensions:
+  - markdown.extensions.admonition
 pages:
 - Home: index.md
 - Basics:
@@ -25,8 +29,10 @@ pages:
    - All Available Hooks: hooks-db.md
 - Writing Extensions:
   - Basics: extensions/basics.md
-  # - civix: extensions/civix.md
-  # - Anatomy of Files: extensions/files.md
+  - Using civix: extensions/civix.md
+  - Anatomy of Files: extensions/files.md
+  - Advanced Patterns: extensions/advanced.md
+  - Troubleshooting: extensions/troubleshooting.md
   # - Using hooks: extensions/using-hooks.md
   # - Customizing Screens: extensions/customize-screens.md
   # - Creating Pages: Forms/extensions/create-page.md