-
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
ublaboo -> contributte, move docs example to planette
- Loading branch information
1 parent
f3f4250
commit c7f38d5
Showing
58 changed files
with
274 additions
and
371 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,123 @@ | ||
# Anabelle | ||
|
||
## Api documentation generator (JSON-RPC / REST) | ||
|
||
(No matter whether you're using REST or JSON-RPC or some other api architecture/scheme) | ||
|
||
### Example (demo) | ||
|
||
There is an example repository: [here](http://github.com/planette/playground/tree/master/contributte-anabelle). Generated documentation can be viewed here: [examples.contributte.org/packages/anabelle/](https://examples.contributte.org/packages/datagrid/). | ||
|
||
### Extended Markdown syntax | ||
|
||
#### `#include <file.md>` | ||
|
||
```md | ||
#include variables.md | ||
``` | ||
|
||
#### `$variable = <value>` | ||
|
||
```md | ||
$uuid = 123e4567-e89b-12d3-a456-426655440000 | ||
``` | ||
|
||
Inline variable usage | ||
|
||
```md | ||
User uuid is {$uuid} | ||
``` | ||
|
||
#### `$$blockVariable ... $$` | ||
|
||
```md | ||
$$successEmptyResponse | ||
{ | ||
"jsonrpc": "2.0", | ||
"result": {}, | ||
"id": null | ||
} | ||
$$ | ||
``` | ||
|
||
Block variable usage | ||
|
||
```md | ||
Server returns response: | ||
|
||
{$$successEmptyResponse} | ||
``` | ||
|
||
#### `@ <sectionName>:<sectionFile.md>` | ||
|
||
High-level section definition. This macro available only in `index.md` file. | ||
|
||
```md | ||
@ Home:home.md | ||
@ About project:about.md | ||
``` | ||
|
||
#### `@@ <sectionName>:<sectionFile.md>` | ||
|
||
Method section definition. This macro available only in `index.md` file. | ||
|
||
```md | ||
@@ user.login:methods/user.login.md | ||
@@ user.logout:methods/user.logout.md | ||
@@ user.register:methods/user.register.md | ||
@@ user.confirm-registration:methods/user.confirm-registration.md | ||
``` | ||
|
||
#### `[File link](foo/bar/data.json)` | ||
|
||
[File link](foo/bar/data.json) will create a link to file (`foo/bar/data.json`). The file will be copied to documentation output directory for safety reasons. | ||
|
||
```md | ||
[File link](foo/bar/data.json) | ||
[Project root directory file link](../app/schema/user.json) | ||
``` | ||
|
||
|
||
## How to use anabelle | ||
|
||
```bash | ||
~ $ cd myApi | ||
~/myApi $ composer require contributte/anabelle | ||
~/myApi $ vendor/bin/anabelle docs-src docs | ||
``` | ||
|
||
### CLI options | ||
|
||
#### Automatically overwrite output directory | ||
|
||
```bash | ||
vendor/bin/anabelle docs-src docs -o | ||
// Or | ||
vendor/bin/anabelle docs-src docs --overwriteOutputDir | ||
``` | ||
|
||
#### Add http auth to generated files | ||
|
||
**Beware! Anabelle generates by default .html files. If you are using http auth, it generates .php files due to the need of validating http auth headers.** | ||
|
||
```bash | ||
vendor/bin/anabelle docs-src docs -u user -p pass | ||
// Or | ||
vendor/bin/anabelle docs-src docs --httpAuthUser user -httpAuthPass pass | ||
``` | ||
|
||
## Generator workflow | ||
|
||
1. Most important (and only required) file is `index.md`. In this file, you can use only (different Markdown markup is ignored in `index.md`): | ||
- `# <h1>` | ||
- `## <h2>` | ||
- `#include <file.md>` | ||
- `$variable = <value>` | ||
- `$$blockVariable ... $$` | ||
- `@ <sectionName>:<sectionFile.md>` | ||
- `@@ <sectionName>:<sectionFile.md>`) | ||
1. `#include` macros are replaced | ||
1. `<h1>` is used as documentation page title (only the first found one is used) | ||
1. `<h2>` can be used wherever you want in the sidebar | ||
1. `@` and `@@` sections are rendered in the sidebar nav | ||
1. Content of `@` and `@@` sections is rendered into separate files and loaded into the main section detail after clicking particular section link in the nav |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,131 +1,45 @@ | ||
[![Build Status](https://travis-ci.org/ublaboo/anabelle.svg?branch=master)](https://travis-ci.org/ublaboo/anabelle) | ||
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/ublaboo/anabelle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/ublaboo/anabelle/?branch=master) | ||
[![Latest Stable Version](https://poser.pugx.org/ublaboo/anabelle/v/stable)](https://packagist.org/packages/ublaboo/anabelle) | ||
[![License](https://poser.pugx.org/ublaboo/anabelle/license)](https://packagist.org/packages/ublaboo/anabelle) | ||
[![Total Downloads](https://poser.pugx.org/ublaboo/anabelle/downloads)](https://packagist.org/packages/ublaboo/anabelle) | ||
[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/ublaboo/help) | ||
# Anabelle | ||
|
||
ublaboo/anabelle | ||
================ | ||
[![Build Status](https://img.shields.io/travis/contributte/anabelle.svg?style=flat-square)](https://travis-ci.org/contributte/anabelle) | ||
[![Code coverage](https://img.shields.io/coveralls/contributte/anabelle.svg?style=flat-square)](https://coveralls.io/r/contributte/anabelle) | ||
[![Licence](https://img.shields.io/packagist/l/contributte/anabelle.svg?style=flat-square)](https://packagist.org/packages/contributte/anabelle) | ||
[![Downloads this Month](https://img.shields.io/packagist/dm/contributte/anabelle.svg?style=flat-square)](https://packagist.org/packages/contributte/anabelle) | ||
[![Downloads total](https://img.shields.io/packagist/dt/contributte/anabelle.svg?style=flat-square)](https://packagist.org/packages/contributte/anabelle) | ||
[![Latest stable](https://img.shields.io/packagist/v/contributte/anabelle.svg?style=flat-square)](https://packagist.org/packages/contributte/anabelle) | ||
[![PHPStan](https://img.shields.io/badge/PHPStan-enabled-brightgreen.svg?style=flat-square)](https://github.com/phpstan/phpstan) | ||
|
||
## Api documentation generator (JSON-RPC / REST) | ||
![](https://github.com/contributte/anabelle/blob/master/.docs/assets/anabelle.png "Anabelle") | ||
|
||
(No matter whether you're using REST or JSON-RPC or some other api architecture/scheme) | ||
## Discussion / Help | ||
|
||
### Example | ||
[![Join the chat](https://img.shields.io/gitter/room/contributte/contributte.svg?style=flat-square)](http://bit.ly/ctteg) | ||
|
||
There is an example documentation directory: `demo`, as you can see above. Generated example documentation: https://contributte.github.io/anabelle. | ||
## Documentation | ||
|
||
### Extended Markdown syntax | ||
- [Api documentation generator \(JSON-RPC / REST\)](.docs/README.md#api-documentation-generator-json-rpc--rest) | ||
- [How to use anabelle](.docs/README.md#how-to-use-anabelle) | ||
- [Generator workflow](.docs/README.md#generator-workflow) | ||
|
||
#### `#include <file.md>` | ||
## Versions | ||
|
||
```md | ||
#include variables.md | ||
``` | ||
| State | Version | Branch | Nette | PHP | | ||
|--------|----------|----------|--------|---------| | ||
| stable | `^2.0.0` | `master` | `3.0+` | `>=7.1` | | ||
|
||
#### `$variable = <value>` | ||
## Maintainers | ||
|
||
```md | ||
$uuid = 123e4567-e89b-12d3-a456-426655440000 | ||
``` | ||
<table> | ||
<tbody> | ||
<tr> | ||
<td align="center"> | ||
<a href="https://github.com/paveljanda"> | ||
<img width="150" height="150" src="https://avatars0.githubusercontent.com/u/1488874?s=150&v=4"> | ||
</a> | ||
</br> | ||
<a href="https://github.com/paveljanda">Pavel Janda</a> | ||
</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
|
||
Inline variable usage | ||
|
||
```md | ||
User uuid is {$uuid} | ||
``` | ||
|
||
#### `$$blockVariable ... $$` | ||
|
||
```md | ||
$$successEmptyResponse | ||
{ | ||
"jsonrpc": "2.0", | ||
"result": {}, | ||
"id": null | ||
} | ||
$$ | ||
``` | ||
|
||
Block variable usage | ||
|
||
```md | ||
Server returns response: | ||
|
||
{$$successEmptyResponse} | ||
``` | ||
|
||
#### `@ <sectionName>:<sectionFile.md>` | ||
|
||
High-level section definition. This macro available only in `index.md` file. | ||
|
||
```md | ||
@ Home:home.md | ||
@ About project:about.md | ||
``` | ||
|
||
#### `@@ <sectionName>:<sectionFile.md>` | ||
|
||
Method section definition. This macro available only in `index.md` file. | ||
|
||
```md | ||
@@ user.login:methods/user.login.md | ||
@@ user.logout:methods/user.logout.md | ||
@@ user.register:methods/user.register.md | ||
@@ user.confirm-registration:methods/user.confirm-registration.md | ||
``` | ||
|
||
#### `[File link](foo/bar/data.json)` | ||
|
||
[File link](foo/bar/data.json) will create a link to file (`foo/bar/data.json`). The file will be copied to documentation output directory for safety reasons. | ||
|
||
```md | ||
[File link](foo/bar/data.json) | ||
[Project root directory file link](../app/schema/user.json) | ||
``` | ||
|
||
|
||
## How to use anabelle | ||
|
||
```bash | ||
~ $ cd myApi | ||
~/myApi $ composer require ublaboo/anabelle | ||
~/myApi $ vendor/bin/anabelle docs-src docs | ||
``` | ||
|
||
### CLI options | ||
|
||
#### Automatically overwrite output directory | ||
|
||
```bash | ||
vendor/bin/anabelle docs-src docs -o | ||
// Or | ||
vendor/bin/anabelle docs-src docs --overwriteOutputDir | ||
``` | ||
|
||
#### Add http auth to generated files | ||
|
||
**Beware! Anabelle generates by default .html files. If you are using http auth, it generates .php files due to the need of validating http auth headers.** | ||
|
||
```bash | ||
vendor/bin/anabelle docs-src docs -u user -p pass | ||
// Or | ||
vendor/bin/anabelle docs-src docs --httpAuthUser user -httpAuthPass pass | ||
``` | ||
|
||
## Generator workflow | ||
|
||
1. Most important (and only required) file is `index.md`. In this file, you can use only (different Markdown markup is ignored in `index.md`): | ||
- `# <h1>` | ||
- `## <h2>` | ||
- `#include <file.md>` | ||
- `$variable = <value>` | ||
- `$$blockVariable ... $$` | ||
- `@ <sectionName>:<sectionFile.md>` | ||
- `@@ <sectionName>:<sectionFile.md>`) | ||
1. `#include` macros are replaced | ||
1. `<h1>` is used as documentation page title (only the first found one is used) | ||
1. `<h2>` can be used wherever you want in the sidebar | ||
1. `@` and `@@` sections are rendered in the sidebar nav | ||
1. Content of `@` and `@@` sections is rendered into separate files and loaded into the main section detail after clicking particular section link in the nav | ||
Thank you for testing, reporting and contributing. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.