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

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

schenke-io / packaging-tools

Maintainers

Details