https://github.com/krakphp/peridocs

Peridot plugin for generating markdown documentation from your tests
https://github.com/krakphp/peridocs

auto-docs documentation peridot peridot-plugin php

Last synced: about 1 month ago
JSON representation

Peridot plugin for generating markdown documentation from your tests

• Host: GitHub
• URL: https://github.com/krakphp/peridocs
• Owner: krakphp
• Created: 2018-02-11T01:09:22.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2020-02-22T19:53:23.000Z (almost 5 years ago)
• Last Synced: 2024-12-01T03:08:16.627Z (about 1 month ago)
• Topics: auto-docs, documentation, peridot, peridot-plugin, php
• Language: PHP
• Size: 9.77 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Peridocs

Peridocs is a Peridot plugin that generates automated markdown documentation from your peridot tests. I've found that my peridot tests are usually the best source of documentation. This project allows you to utilize your test documentation in an automated way.

## Installation

Load with composer as a dev dependency: `krak/peridocs`.

In your `peridot.php` configuration file, add the following:

```php

 '
{signature}
',

            'showLinks' => false,

            'nsPrefix' => 'Acme\\Prefix\\',

            'numTableRows' => 4,

        ]);

    });

};

```


## Usage

Once registered, you can utilize the `docFn` function in your tests to enable documentation for the given test.

```php

// function to test

function addMaybe(int $a, int $b): int {

    return $a == $b ? $a * $a : $a + $b;

}

// in some spec.php file

describe('Demo Package', function() {

    describe('addMaybe', function() {

        docFn(addMaybe::class); // this is the fully qualified name for the function e.g. 'Acme\Prefix\addMaybe'

        docIntro('`addMaybe` optional foreword/introduction.');

        it('usually adds two numbers together', function() {

            expect(addMaybe(1, 2))->equal(3);

        });

        it('but will multiply the two numbers when they are equal', function() {

            expect(addMaybe(3, 3))->equal(9);

        });

        docOutro('This is the optional outro/conclusion to be appended to the text');

    });

});

```

Now, you can generate the markdown by running peridot with the peridocs reporter.

```

./vendor/bin/peridot -r peridocs

```

It should output the following markdown:

    
addMaybe(int $a, int $b): int


    **Name:** Krak\Peridocs\addMaybe

    `addMaybe` optional foreword/introduction.

    usually adds two numbers together:

    ```php

    expect(addMaybe(1, 2))->equal(3);

    ```

    but will multiply the two numbers when they are equal:

    ```php

    expect(addMaybe(3, 3))->equal(9);

    ```

    This is the optional outro/conclusion to be appended to the text