Skip to content

Commit

Permalink
ublaboo -> contributte, move docs example to planette
Browse files Browse the repository at this point in the history
  • Loading branch information
paveljanda committed May 4, 2020
1 parent f3f4250 commit c7f38d5
Show file tree
Hide file tree
Showing 58 changed files with 274 additions and 371 deletions.
123 changes: 123 additions & 0 deletions .docs/README.md
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
Binary file added .docs/assets/anabelle.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
154 changes: 34 additions & 120 deletions README.md
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.
11 changes: 5 additions & 6 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "ublaboo/anabelle",
"name": "contributte/anabelle",
"type": "library",
"description": "JSON-RPC Api documentation generator",
"keywords": ["json-rpc", "json", "rpc", "api", "documentation", "docs", "generator", "readme"],
"homepage": "https://ublaboo.org/anabelle",
"homepage": "https://contributte.org/anabelle",
"license": ["MIT"],
"support": {
"issues": "https://github.com/ublaboo/anabelle/issues"
"issues": "https://github.com/contributte/anabelle/issues"
},
"authors": [
{
Expand All @@ -16,12 +16,12 @@
],
"autoload": {
"psr-4": {
"Ublaboo\\Anabelle\\": "src/"
"Contributte\\Anabelle\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"Ublaboo\\Anabelle\\Tests\\": "tests"
"Contributte\\Anabelle\\Tests\\": "tests"
}
},
"require": {
Expand All @@ -40,7 +40,6 @@
"src/anabelle"
],
"scripts": {
"generateDocs": "src/anabelle docs-src docs -o",
"tests": "vendor/bin/tester tests",
"phpstan": "vendor/bin/phpstan analyse src -c vendor/gamee/php-code-checker-rules/phpstan.neon --level 7",
"phpcs": "vendor/bin/phpcs --standard=vendor/gamee/php-code-checker-rules/ruleset.xml --extensions=php,phpt --tab-width=4 --ignore=temp -sp src",
Expand Down
5 changes: 0 additions & 5 deletions docs-src/about.md

This file was deleted.

32 changes: 0 additions & 32 deletions docs-src/home.md

This file was deleted.

11 changes: 0 additions & 11 deletions docs-src/index.md

This file was deleted.

19 changes: 0 additions & 19 deletions docs-src/methods/user.login.md

This file was deleted.

Loading

0 comments on commit c7f38d5

Please sign in to comment.