Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

Disclaimer

⚠️	This project is no longer being maintained.

Composer	contributte/anabelle
Version
PHP
License

About

Anabelle is a JSON-RPC API documentation generator. It supports both JSON-RPC and REST architectures and provides an extended Markdown syntax for creating rich, interactive API documentation.

Usage

To install the latest version of contributte/anabelle use Composer.

composer require contributte/anabelle

How to use anabelle

cd myApi
composer require contributte/anabelle
vendor/bin/anabelle docs-src docs

CLI options

Automatically overwrite output directory

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.

vendor/bin/anabelle docs-src docs -u user -p pass
// Or
vendor/bin/anabelle docs-src docs --httpAuthUser user -httpAuthPass pass

Extended Markdown syntax

#include <file.md>

#include variables.md

$variable = <value>

$uuid = 123e4567-e89b-12d3-a456-426655440000

Inline variable usage

User uuid is {$uuid}

$$blockVariable ... $$

$$successEmptyResponse
{
	"jsonrpc": "2.0",
	"result": {},
	"id": null
}
$$

Block variable usage

Server returns response:

{$$successEmptyResponse}

@ <sectionName>:<sectionFile.md>

High-level section definition. This macro available only in index.md file.

@ Home:home.md
@ About project:about.md

@@ <sectionName>:<sectionFile.md>

Method section definition. This macro available only in index.md file.

@@ 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 will create a link to file (foo/bar/data.json). The file will be copied to documentation output directory for safety reasons.

[File link](foo/bar/data.json)
[Project root directory file link](../app/schema/user.json)

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>)
2. #include macros are replaced
3. <h1> is used as documentation page title (only the first found one is used)
4. <h2> can be used wherever you want in the sidebar
5. @ and @@ sections are rendered in the sidebar nav
6. Content of @ and @@ sections is rendered into separate files and loaded into the main section detail after clicking particular section link in the nav

Examples

• http://github.com/contributte/playground/tree/master/contributte-anabelle (example project)
• https://examples.contributte.org/packages/anabelle/ (generated documentation)
• https://github.com/contributte/playground (playground)
• https://contributte.org/examples.html (more examples)

Versions

State	Version	Branch	Nette	PHP
dev	^6.0.0	master	3.0+	>=8.1
stable	^5.0.0	master	3.0+	>=8.1

Development

This package was maintained by these authors.

---

Consider to support contributte development team. Also thank you for using this package.