Getting Started

Introduction

Welcome to the autodocs wiki!

Autodocs is a PHP library designed to facilitate building highly customizable automated docs based on simple templates. It provides a layer of abstraction on top of which you can create your own documentation factory.

Pages are defined as classes that follow a known interface. Data sources can be autoloaded as JSON cache files, a design that facilitates distributed setups where data comes from varied sources. This distributed approach facilitates integrating Autodocs with existing workflows and pipelines, especially when using GitHub Actions.

Adding Autodocs to your Minicli Project

Autodocs was designed to be used as a service within Minicli applications. From your Minicli app, start by requiring the Autodocs library with:

composer require erikaheidi/autodocs

Configuring the Autodocs Service

Next, you should configure Autodocs options. The recommended way to do so is by creating an autodocs.php configuration file in the config folder of your Minicli app.

Autodocs expects an autodocs entry in the main app configuration, with a few required settings:

• templates_dir: where to find .tpl files that may be used as page templates. The use of templates is not mandatory, but it can be helpful to facilitate content layout updates without having to change page classes.
• cache_dir: .json files in this directory will be automatically registered as a DataFeed object within the main Autodocs service.
• pages: an array with classes that should be registered as Buildable Pages.
• storage: (Optional) a class that implements StorageInterface, able to handle filesystem access to save and retrieve files.

Example Configuration

The following configuration can be used to set up Autodocs within Minicli applications.

<?php

declare(strict_types=1);

use Autodocs\Page\ExamplePage;

return [
    'autodocs' => [
        // Pages to Build
        'pages' => [
            ExamplePage::class
        ],
        // Build Output Folder
        'output' => envconfig('AUTODOCS_OUTPUT', __DIR__.'/../storage/content'),
        // Cache Folder - where to look for cache json files
        'cache_dir' => envconfig('AUTODOCS_CACHE', __DIR__.'/../storage/cache'),
        // Templates directory
        'templates_dir' => envconfig('AUTODOCS_TEMPLATES', __DIR__.'/../storage/templates')
    ]
];