Wallogit.com
2017 © Pedro PelĂĄez
Automatic configuration provider for Sami documentation generator
I personally use Sami for generating API documentation for number of my projects. However, to generate that documentation, I need to set up a configuration for each project that only varies slightly per project. Thus I created this composer package that can automatically figure out the configuration and set it up properly for each project., (*1)
Essentially, by using this automatic configuration utility, you can have Sami configured with some defaults that are figured from rest of the project files rather than having to manually duplicate them into the Sami config., (*2)
, (*3)
To add this configuration utility to your project, you should first include it via composer:, (*4)
$ composer require --dev riimu/sami-config
Then you should create a file named sami_config.php in your project root directory that simply contains, (*5)
<?php return require __DIR__ . '/vendor/riimu/sami-config/config.php';
The sami_config.php can now be used as the configuration for the documentation generator, e.g., (*6)
$ sami.php update sami_config.php
The documentation is generted from the src directory in the project root directory., (*7)
No theme will be set for the generated documentation, but you can use environmental variable SAMI_THEME to
set a theme by setting it to a path to directory that contains a theme manifest.yml. The directory name and
the name of the theme must match., (*8)
The title for the documentation is parsed from the root README.md file by taking text from the first line,
which is indicated by markdown as a title. Then the word API is appended to it., (*9)
For example, if documentation was generated from this repository, the title would be
Riimu's Automatic Sami Configuration API., (*10)
If no title can be determined, an exception will be thrown and the process is interrupted., (*11)
The configuration utility automatically looks up the latest semver stable tag from the repository and checkouts that
for the purpose of generating the documentation. Not that if you create the tags as releases in Github, remember
to run git fetch in order to also get the tags locally., (*12)
After the documentation is generated, the previous selected working state is checked out again., (*13)
If no applicable tags can be found or the workspace is not clean for checking out another tag, an exception will be thrown and the process interrupted., (*14)
The build directory will be set to build/doc and the cache path to build/cache in the project root directory.
Do note that both of these directories will be cleared entirely before the documentation generation process., (*15)
The repository url will be set as a github repository url based on what is set as the url for origin remote in the
local git repository., (*16)
If no valid github url is set as the remote url for origin, an exception will be thrown and the process interrupted., (*17)
This package is Copyright (c) 2018 Riikka KalliomÀki., (*18)
See LICENSE for license and copying information., (*19)
Automatic configuration provider for Sami documentation generator
MIT
config documentation sami
Automatic configuration provider for Sami documentation generator
MIT
config documentation sami