Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

renamed .wiki to .md #26

Merged
merged 1 commit into from
Dec 12, 2012
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 10 additions & 15 deletions README.md
Original file line number Original file line Diff line number Diff line change
@@ -1,5 +1,3 @@
# Li3 Docs

Li3_docs is a **Lithium plugin**, NOT a Lithium app. Furthermore, by itself it is a VIEWER ONLY and contains no actual documentation other than its own. Li3_docs is a **Lithium plugin**, NOT a Lithium app. Furthermore, by itself it is a VIEWER ONLY and contains no actual documentation other than its own.


Once installed in your existing application, however, it generates documentation from your app's docblocks in real-time, which is all accessible from http://yourapp.tld/docs/. Not only that, but it will generate documentation for your plugins, too. Including itself; so it is self-replicating in a way. In this vein, it becomes part of a series of plugins required in order to obtain various documentation volumes of interest. Once installed in your existing application, however, it generates documentation from your app's docblocks in real-time, which is all accessible from http://yourapp.tld/docs/. Not only that, but it will generate documentation for your plugins, too. Including itself; so it is self-replicating in a way. In this vein, it becomes part of a series of plugins required in order to obtain various documentation volumes of interest.
Expand All @@ -16,7 +14,7 @@ So the Lithium documentation plugin (Li3 Docs) is a tool for creating automatica


For generating documentation, Li3 Docs relies on PHP documentation blocks, or _docblocks_. These docblocks can appear above classes, methods, properties, etc., and contain three things: a short description, a longer description (often including usage examples), and docblock _tags_, which are denoted by an `@` symbol, followed by a keyword. A typical docblock might look something like this: For generating documentation, Li3 Docs relies on PHP documentation blocks, or _docblocks_. These docblocks can appear above classes, methods, properties, etc., and contain three things: a short description, a longer description (often including usage examples), and docblock _tags_, which are denoted by an `@` symbol, followed by a keyword. A typical docblock might look something like this:


```php {{{
/** /**
* Contains an instance of the `Request` object with all the details of the HTTP request that * Contains an instance of the `Request` object with all the details of the HTTP request that
* was dispatched to the controller object. Any parameters captured in routing, such as * was dispatched to the controller object. Any parameters captured in routing, such as
Expand All @@ -27,27 +25,23 @@ For generating documentation, Li3 Docs relies on PHP documentation blocks, or _d
* @var object * @var object
*/ */
public $request = null; public $request = null;
``` }}}


This docblock documents a class property, and contains a short description and two docblock tags. The tags to be used in a docblock vary by what is being documented. A property docblock should contain a `@var` tag that describes what type of value the property holds, while methods have a series of `@param` tags and a `@return` tag. This docblock documents a class property, and contains a short description and two docblock tags. The tags to be used in a docblock vary by what is being documented. A property docblock should contain a `@var` tag that describes what type of value the property holds, while methods have a series of `@param` tags and a `@return` tag.


There are also general tags which can be added to any docblock. These include the `@see` tag, which allows you to link to another class, method or property, and the `@link` tag, which allows you to link to an arbitrary URL. There are also general tags which can be added to any docblock. These include the `@see` tag, which allows you to link to another class, method or property, and the `@link` tag, which allows you to link to an arbitrary URL.


### Markdown syntax ### Markdown syntax


Docblock descriptions are written in Markdown format, with a few conventions. Namely, any code references or identifiers should be enclosed in backticks. This includes namespaces, classes, variable names, and keywords like `true`, `false` and `null`. Extended code examples should be written enclosed in three sets of curly braces, i.e.: Docblock descriptions are written in Markdown format, with a few conventions. Namely, any code references or identifiers should be enclosed in backticks. This includes namespaces, classes, variable names, and keywords like `true`, `false` and `null`. Extended code examples should be written enclosed in three sets of curly braces, i.e.: {‍{{ // Code goes here }}}.

```php
{{{ // Code goes here }}}
```


### Code embedding ### Code embedding


In order to improve the testability of documented code examples, and to help ensure that code and documentation stay in sync, Li3 Docs supports a special syntax that allows code from class methods to be embedded inline inside Markdown text. Consider the following: In order to improve the testability of documented code examples, and to help ensure that code and documentation stay in sync, Li3 Docs supports a special syntax that allows code from class methods to be embedded inline inside Markdown text. Consider the following:


```php {{{
{{{ embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(1-3) }‍}} {{{ embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(1-3) }‍}}
``` }}}


This will embed code from the `testSetAndGetCurrentEnvironment()` method of the `Environment` test case, from line 1 through line 3 as an inline code example in the Markdown text. This way, whenever the code changes, the tests change to match it, and the documentation stays up-to-date with what's in the test. This will embed code from the `testSetAndGetCurrentEnvironment()` method of the `Environment` test case, from line 1 through line 3 as an inline code example in the Markdown text. This way, whenever the code changes, the tests change to match it, and the documentation stays up-to-date with what's in the test.


Expand All @@ -57,11 +51,11 @@ Finally, since explanations and descriptions of code can fall out of sync with e


Once loaded into your application the plugin will enable browsing for all added libraries. In some cases it may be desired to disable browsing for certain libraries. In order to do so pass the `'index'` option in the second parameter when adding Li3 Docs: Once loaded into your application the plugin will enable browsing for all added libraries. In some cases it may be desired to disable browsing for certain libraries. In order to do so pass the `'index'` option in the second parameter when adding Li3 Docs:


```php {{{
Libraries::add('li3_docs', array( Libraries::add('li3_docs', array(
'index' => array('lithium', 'li3_bot') 'index' => array('lithium', 'li3_bot')
)); ));
``` }}}


### Searching ### Searching


Expand All @@ -73,6 +67,7 @@ The plugin now features a symbol-based live search. Search for classes, methods


To update the search database, run the symbol harvesting task: To update the search database, run the symbol harvesting task:


``` {{{
$ li3 harvest $ li3 harvest
``` }}}

2 changes: 1 addition & 1 deletion config/docs/index.json
Original file line number Original file line Diff line number Diff line change
@@ -1,5 +1,5 @@
{ {
"category": "libraries", "category": "libraries",
"title": "Lithium Documentation Tool", "title": "Lithium Documentation Tool",
"description": "The Lithium documentation tool provides automated documentation display and extraction from class API documentation and from `readme.wiki` files." "description": "The Lithium documentation tool provides automated documentation display and extraction from class API documentation and from `readme.md` files."
} }
2 changes: 1 addition & 1 deletion controllers/ApiBrowserController.php
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ class ApiBrowserController extends \lithium\action\Controller {
* *
* @var string * @var string
*/ */
public $docFile = array('readme.wiki', 'readme.md'); public $docFile = array('readme.md');


protected function _init() { protected function _init() {
parent::_init(); parent::_init();
Expand Down
58 changes: 0 additions & 58 deletions readme.wiki

This file was deleted.