{"id":22092095,"url":"https://github.com/krakphp/peridocs","last_synced_at":"2025-10-13T12:34:05.455Z","repository":{"id":57009052,"uuid":"121069717","full_name":"krakphp/peridocs","owner":"krakphp","description":"Peridot plugin for generating markdown documentation from your tests","archived":false,"fork":false,"pushed_at":"2020-02-22T19:53:23.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-12T16:36:39.882Z","etag":null,"topics":["auto-docs","documentation","peridot","peridot-plugin","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krakphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-11T01:09:22.000Z","updated_at":"2020-02-22T19:52:05.000Z","dependencies_parsed_at":"2022-08-21T12:30:08.298Z","dependency_job_id":null,"html_url":"https://github.com/krakphp/peridocs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/krakphp/peridocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krakphp%2Fperidocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krakphp%2Fperidocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krakphp%2Fperidocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krakphp%2Fperidocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krakphp","download_url":"https://codeload.github.com/krakphp/peridocs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krakphp%2Fperidocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015056,"owners_count":26085643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto-docs","documentation","peridot","peridot-plugin","php"],"created_at":"2024-12-01T03:08:19.471Z","updated_at":"2025-10-13T12:34:05.416Z","avatar_url":"https://github.com/krakphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Peridocs\n\nPeridocs 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.\n\n## Installation\n\nLoad with composer as a dev dependency: `krak/peridocs`.\n\nIn your `peridot.php` configuration file, add the following:\n\n```php\n\u003c?php\n\nuse Krak\\Peridocs;\n\nreturn function($emitter) {\n    // the second parameter is optional and is used to configure the DocsContext\n    Peridocs\\bootstrap($emitter, function() {\n        return new DocsContext(null, [\n            'headerFmt' =\u003e '\u003ch3 id=\"{id}\"\u003e{signature}\u003c/h3\u003e',\n            'showLinks' =\u003e false,\n            'nsPrefix' =\u003e 'Acme\\\\Prefix\\\\',\n            'numTableRows' =\u003e 4,\n        ]);\n    });\n};\n```\n\n## Usage\n\nOnce registered, you can utilize the `docFn` function in your tests to enable documentation for the given test.\n\n```php\n// function to test\nfunction addMaybe(int $a, int $b): int {\n    return $a == $b ? $a * $a : $a + $b;\n}\n\n// in some spec.php file\ndescribe('Demo Package', function() {\n    describe('addMaybe', function() {\n        docFn(addMaybe::class); // this is the fully qualified name for the function e.g. 'Acme\\Prefix\\addMaybe'\n        docIntro('`addMaybe` optional foreword/introduction.');\n\n        it('usually adds two numbers together', function() {\n            expect(addMaybe(1, 2))-\u003eequal(3);\n        });\n        it('but will multiply the two numbers when they are equal', function() {\n            expect(addMaybe(3, 3))-\u003eequal(9);\n        });\n\n        docOutro('This is the optional outro/conclusion to be appended to the text');\n    });\n});\n```\n\nNow, you can generate the markdown by running peridot with the peridocs reporter.\n\n```\n./vendor/bin/peridot -r peridocs\n```\n\nIt should output the following markdown:\n\n    \u003ch3 id=\"api-krak-peridocs-addmaybe\"\u003eaddMaybe(int $a, int $b): int\u003c/h3\u003e\n\n    **Name:** Krak\\Peridocs\\addMaybe\n\n    `addMaybe` optional foreword/introduction.\n\n    usually adds two numbers together:\n\n    ```php\n    expect(addMaybe(1, 2))-\u003eequal(3);\n    ```\n\n    but will multiply the two numbers when they are equal:\n\n    ```php\n    expect(addMaybe(3, 3))-\u003eequal(9);\n    ```\n\n    This is the optional outro/conclusion to be appended to the text\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrakphp%2Fperidocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrakphp%2Fperidocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrakphp%2Fperidocs/lists"}