On the CloudWays blog there's a new tutorial posted showing you how to create project documentation with Sami, a tool that takes the DocBlock information already in your code and makes it into something more human-readable.

Developers regularly create large blocks of code that form parts of API’s and other mid to large level projects. While there is a (more or less) agreed upon convention for code writing, every developer has a personal comment and documentation writing standards. Some add small cryptic notes while others attach full-length Google Docs that document the method or class in painful details. This problem becomes very severe when the number of end users increases and there is a need for proper documentation of the project.

[...] DocBlocks are important because they are used by a well known Symfony document generator package called Sami. Very popular in PHP community, Sami also provides the ability to create custom twig templates and work with versioned documentation on GitHub. In this article, I will use Sami and a GitHub project Sync Mysql data with Elasticsearch to automatically generate documentation.

The tutorial then helps you get the Sami package installed via Composer and how to execute it to ensure it's working as expected. Next it points you to a project to clone to help with the MySQL-to-Elasticsearch interface. It then helps with the creation of a configuration file, the results of a build and some additional tips for customizing the configuration for your environment.

The SitePoint PHP blog has a new tutorial posted today showing you how to generate API documentation with Sami, a "Friends of PHP" project that's currently used to generate API documentation similar to what the Symfony project provides. In this case "API" refers to your class and method structures, not something like a REST API.

Documenting your methods, classes, and functions is becoming second nature for everyone, so it makes sense to have a way to generate a separate documentation instead of navigating through the source code. In this article, I’m going to introduce you to Sami, the new API documentation generator.

He starts with a brief introduction to the DocBlock commenting methods and why you might want to choose Sami over other document generation tools (like phpDocumentor). He then helps you get Sami installed as a phar archive and how to use it to generate the document output for the Laravel Illuminate package. He includes the code you can use to set up the Sami configuration and an example of the output from the command execution. He then includes a bit about the versioning of the documentation, using themes and customizing the look and feel through custom assets and markup changes.

Fabien Potencier has released a new tool to the open source community today - a documentation generation tool called Sami.

Nowadays, phpDocumentor version 2 is probably the best option out there as it has a good architecture, it works fine, it is extensible, and quite a few big PHP projects is already using it. And that's fine. I don't want to compete with it, I don't want to replace it, I'm just open sourcing some code used by Symfony, Twig, and Silex because I'm not comfortable with closed-source software. And to be totally honest and transparent, I have not released the code before because it was not "good enough".

He gives an example of how to install and use Sami - configuring the directories to parse and setting up a custom theme for the resulting generated documentation (using regular CSS and HTML definitions).