README

Packaging Tools

This package is a collection of tools to simplify the package and project development.

The main elements are:

• Markdown Assemble the readme.md file out of small markdown files, class comments and other sources
• Badge build the badge custom or from existing files
• Setup read the .packaging-tools.neon configuration file and modify scripts in composer.json

• Packaging Tools
  • Installation
  • Concept
  • Configuration
  • Classes
    • MarkdownAssembler
      • How to assemble a markdown
      • Public methods of MarkdownAssembler
      • Details of addTableFromFile()
      • Details of addTableFromArray()
    • MakeBadge
      • Public methods of MakeBadge
    • ClassData

Installation

Install the package with composer:

  composer require schenke-io/packaging-tools

Add the setup command into composer.json under scripts.

{
    
    
    "scripts": {
        "setup": "SchenkeIo\\PackagingTools\\Setup::handle"    
    }
    
}

Start the setup:

  composer setup

and check all available setup parameters:

  composer setup help

Concept

This package follows the following concept:

• setup and configuration is controlled by a config file
• manual edits have higher priority than automatics
• when manual edita would be overwritten there is a warning
• the documentation is organised out of components which get assembled at the end
• important classes and methods are marked and documented
• badges are written from data
• the build process is controlled by script
• missing files are explained with full path

Configuration

Each package is controlled by a config file .packaging-tools.neon . NEON files can be written as YAML or JSON but additionally with comments.

The format can be easily schema verified and is used here as simple key-value-pairs.

Classes

MarkdownAssembler

Assembler of a markdown file

How to assemble a markdown

To assemble a markdown you need these things:

• a directory with well named markdown files
• documentation of classes and methods
• csv files for tables
• a script
  • which writes badges
  • which read and assemble these files

This script can be a script run by php itself or a class file with a static method.

<?php


require "vendor/autoload.php";

use SchenkeIo\PackagingTools\Markdown\MarkdownAssembler;

/*
 * this scripts make the package itself and tests its functionality
 */

try {
    $mda = new MarkdownAssembler(/* subdirectory for markdown include files */);
    $mda->addMarkdown(/* relative to markdown directory */);
    $mda->addTableOfContents();
    // relative to markdown directory
    $mda->addMarkdown("installation.md");
    // makes markdown from a class phpdoc
    $mda->addClassMarkdown(MarkdownAssembler::class);

    // path relative to root directory
    $mda->writeMarkdown("README.md");
} catch (Exception $e) {
    echo "ERROR: " . $e->getMessage() . PHP_EOL;
}

Public methods of MarkdownAssembler

Details of addTableFromFile()

The following extensions for the file are implemented:

Details of addTableFromArray()

The array is expected to have this format:

$arary = [
    ['header 1','header 2','header 3'],
    ['cell 1:1','cell 1:2','cell 1:3'],
    ['cell 2:1','cell 2:2','cell 2:3'],
    ['cell 3:1','cell 3:2','cell 3:3'],
];

and would be rendered like this:

MakeBadge

makes badges in various formats and from many sources

Public methods of MakeBadge

ClassData