jakota/documentation-builder

Build documentation with Sphinx from inside your PHP code.

1.1.0 2023-07-02 07:57 UTC

GPL-2.0-or-later

• Thomas Lüder

README

Build documentation with Sphinx from inside your PHP code.

Prerequisites

• Composer v2
• Docker

Detailed Usage

Add as require-dev

composer require --dev jakota/documentation-builder

Create documentation folder like Documentation in the project root

mkdir ./Documentation

Add documentation blocks aka DocBlocks to your php files

The project needs a Index.rst to start from.

Add the following comment to a file.
Usually the main class or a file in the start folder.
It doesn't matter where this comment is located but it must not be found more than once.

<?php
/** Documentation:Start:Index.rst.
 *
 *Welcome to Your documentation index!
 *====================================
 *
 *.. toctree::
 *   :maxdepth: 2
 *   :caption: Contents:
 *
 *TocTreeInsert
 *
 *Documentation:End
 */

You can edit the text to your liking but don't remove the TocTreeInsert placeholder.

Next you want to add more DocBlocks to your PHP code.

<?php

/** Documentation:Start:TocTree:Demo/Index.rst.
 *
 *Demo Class with cool new features
 *=================================
 *
 *.. toctree::
 *   :maxdepth: 2
 *   :caption: Contents:
 *
 *
 *Documentation:End
 */
class DemoController {

Every line between

/** Documentation:Start:TocTree:Demo/Index.rst.

and

 *Documentation:End
 */

will be coped without the leading * into the file Demo/Index.rst.
And if TocTree: is set, this file will also be added to the TocTree in the main Index.rst.

You can add multiple DocBlocks wherever you want to one file.
But it is important that the indent of every line stays the same per DocBlock.

Config JSON

Create a folder for the config json and static files in your project root and name them whatever you like.

A recommended folder structure looks like this:

--- Project-Root
 |--- .documentation        // folder for the config
 | |- _static               // folder for the static content like images
 | |- _templates            // folder for templates
 | |- documentation.json    // config json
 |- Documentation           // folder for the finished documentation

The content of this documentation.json file looks like this:

{
  "StartFolder": "Classes",
  "DocumentationFolder": "Documentation",
  "DocumentationType": "html",
  "Favicon": "_static/favicon.svg",
  "Project": "Your Awesome Project Name",
  "Copyright": "2023, Your company or Name",
  "Author": "Your company or Name",
  "Release": "1.2.3",
  "StaticFolder": "_static",
  "TemplatesFolder": ""
}

StartFolder and DocumentationFolder are relative to the Project-Root.
StaticFolder and TemplatesFolder are relative to the folder for the config.

Again, you can edit the config to your liking.
But for now only html is supported as DocumentationType.
You will see an error message if the config is not as expected.

Run the build script from your project root

./vendor/bin/documentation-builder {the-path-and-file-name-of-your-config.json}

For example:

./vendor/bin/documentation-builder .documentation/documentation.json

Happy documenting :)