allow referencing the guide from API docs

docs/guide/active-record.md

@@ -2,7 +2,7 @@ Active Record
 =============
 
 Active Record implements the [Active Record design pattern](http://en.wikipedia.org/wiki/Active_record).
-The premise behind Active Record is that an individual [[yii\db\ActiveRecord]] object is associated with a specific row in a database table. The object's attributes are mapped to the columns of the corresponding table. Referencing an Active Record attribute is equivalent to accessing
+The premise behind Active Record is that an individual [[yii\db\ActiveRecord|ActiveRecord]] object is associated with a specific row in a database table. The object's attributes are mapped to the columns of the corresponding table. Referencing an Active Record attribute is equivalent to accessing
 the corresponding table column for that record.
 
 As an example, say that the `Customer` ActiveRecord class is associated with the

extensions/apidoc/commands/RenderController.php

@@ -53,6 +53,7 @@ class RenderController extends Controller
 		$renderer->targetDir = $targetDir;
 		if ($this->guide !== null && $renderer->hasProperty('guideUrl')) {
 			$renderer->guideUrl = './';
+			$renderer->markDownFiles = $this->findMarkdownFiles($this->guide, ['README.md']);
 		}
 
 		$this->stdout('Searching files to process... ');
@@ -116,7 +117,7 @@ class RenderController extends Controller
 
 		// render guide if specified
 		if ($this->guide !== null) {
-			$renderer->renderMarkdownFiles($this->findMarkdownFiles($this->guide, ['README.md']), $this);
+			$renderer->renderMarkdownFiles($this);
 
 			$this->stdout('Publishing images...');
 			FileHelper::copyDirectory(rtrim($this->guide, '/\\') . '/images', $targetDir . '/images');

extensions/apidoc/helpers/ApiMarkdown.php

@@ -29,6 +29,14 @@ class ApiMarkdown extends GithubMarkdown
 
 	protected $context;
 
+	public function prepare()
+	{
+		parent::prepare();
+
+		// add references to guide pages
+		$this->references = array_merge($this->references, static::$renderer->getGuideReferences());
+	}
+
 	/**
 	 * @inheritDoc
 	 */

extensions/apidoc/templates/BaseRenderer.php

@@ -31,7 +31,10 @@ abstract class BaseRenderer extends Component
 	 * @var Context the [[Context]] currently being rendered.
 	 */
 	public $context;
-
+	/**
+	 * @var array files for guide pages
+	 */
+	public $markDownFiles;
 
 	/**
 	 * Renders a given [[Context]].
@@ -49,7 +52,7 @@ abstract class BaseRenderer extends Component
 	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
 	 * @return
 	 */
-	public abstract function renderMarkdownFiles($files, $controller);
+	public abstract function renderMarkdownFiles($controller);
 
 	/**
 	 * creates a link to a type (class, interface or trait)

extensions/apidoc/templates/bootstrap/Renderer.php

@@ -134,11 +134,11 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
 	/**
 	 * Renders a given [[Context]].
 	 *
-	 * @param Context $context the api documentation context to render.
 	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
 	 */
-	public function renderMarkdownFiles($files, $controller)
+	public function renderMarkdownFiles($controller)
 	{
+		$files = $this->markDownFiles;
 		$dir = Yii::getAlias($this->targetDir);
 		if (!is_dir($dir)) {
 			mkdir($dir, 0777, true);
@@ -174,7 +174,7 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
 				];
 				$output = $this->getView()->renderFile($this->guideLayout, $params, $this);
 			}
-			$fileName = 'guide_' . str_replace('.md', '.html', basename($file));
+			$fileName = $this->generateGuideFileName($file);
 			file_put_contents($dir . '/' . $fileName, $output);
 			Console::updateProgress(++$done, $fileCount);
 		}
@@ -183,6 +183,21 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
 		$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
 	}
 
+	protected function generateGuideFileName($file)
+	{
+		return 'guide_' . basename($file, '.md') . '.html';
+	}
+
+	public function getGuideReferences()
+	{
+		$refs = [];
+		foreach($this->markDownFiles as $file) {
+			$refName = 'guide-' . basename($file, '.md');
+			$refs[$refName] = ['url' => $this->generateGuideFileName($file)];
+		}
+		return $refs;
+	}
+
 	protected function fixMarkdownLinks($content)
 	{
 		$content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="guide_\1.html\2"', $content);

extensions/jui/Slider.php

@@ -26,6 +26,9 @@ use yii\helpers\Html;
  */
 class Slider extends Widget
 {
+	/**
+	 * @inheritDoc
+	 */
 	protected $clientEventMap = [
 		'change' => 'slidechange',
 		'create' => 'slidecreate',

extensions/jui/SliderInput.php

@@ -43,6 +43,9 @@ use yii\helpers\Html;
  */
 class SliderInput extends InputWidget
 {
+	/**
+	 * @inheritDoc
+	 */
 	protected $clientEventMap = [
 		'change' => 'slidechange',
 		'create' => 'slidecreate',

extensions/jui/Spinner.php

@@ -37,6 +37,9 @@ use yii\helpers\Html;
  */
 class Spinner extends InputWidget
 {
+	/**
+	 * @inheritDoc
+	 */
 	protected $clientEventMap = [
 		'spin' => 'spin',
 	];

framework/db/ActiveRecord.php

@@ -15,7 +15,61 @@ use yii\helpers\StringHelper;
 /**
  * ActiveRecord is the base class for classes representing relational data in terms of objects.
  *
- * @include @yii/db/ActiveRecord.md
+ * Active Record implements the [Active Record design pattern](http://en.wikipedia.org/wiki/Active_record).
+ * The premise behind Active Record is that an individual [[ActiveRecord]] object is associated with a specific
+ * row in a database table. The object's attributes are mapped to the columns of the corresponding table.
+ * Referencing an Active Record attribute is equivalent to accessing the corresponding table column for that record.
+ *
+ * As an example, say that the `Customer` ActiveRecord class is associated with the `tbl_customer` table.
+ * This would mean that the class's `name` attribute is automatically mapped to the `name` column in `tbl_customer`.
+ * Thanks to Active Record, assuming the variable `$customer` is an object of type `Customer`, to get the value of
+ * the `name` column for the table row, you can use the expression `$customer->name`.
+ * In this example, Active Record is providing an object-oriented interface for accessing data stored in the database.
+ * But Active Record provides much more functionality than this.
+ *
+ * To declare an ActiveRecord class you need to extend [[\yii\db\ActiveRecord]] and
+ * implement the `tableName` method:
+ *
+ * ```php
+ * <?php
+ *
+ * class Customer extends \yii\db\ActiveRecord
+ * {
+ *     /**
+ *      * @return string the name of the table associated with this ActiveRecord class.
+ *      * /
+ *     public static function tableName()
+ *     {
+ *         return 'tbl_customer';
+ *     }
+ * }
+ * ```
+ *
+ * The `tableName` method only has to return the name of the database table associated with the class.
+ *
+ * > Tip: You may also use the [Gii code generator][guide-gii] to generate ActiveRecord classes from your
+ * > database tables.
+ *
+ * Class instances are obtained in one of two ways:
+ *
+ * * Using the `new` operator to create a new, empty object
+ * * Using a method to fetch an existing record (or records) from the database
+ *
+ * Here is a short teaser how working with an ActiveRecord looks like:
+ *
+ * ```php
+ * $user = new User();
+ * $user->name = 'Qiang';
+ * $user->save();  // a new row is inserted into tbl_user
+ *
+ * // the following will retrieve the user 'CeBe' from the database
+ * $user = User::find()->where(['name' => 'CeBe'])->one();
+ *
+ * // this will get related records from table tbl_orders when relation is defined
+ * $orders = $user->orders;
+ * ```
+ *
+ * For more details and usage information on ActiveRecord, see the [guide article on ActiveRecord][guide-active-record].
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Carsten Brandt <mail@cebe.cc>