Menjana dokumentasi PHP dengan Sami

Sami: Penjana dokumentasi API yang kuat untuk php

Menjana dokumentasi berasingan untuk kaedah, kelas, dan fungsi PHP anda adalah amalan terbaik. Artikel ini memperkenalkan Sami, penjana dokumentasi API yang mantap yang memudahkan proses ini, meningkatkan kebolehbacaan dan kebolehcapaian.

Ciri -ciri utama Sami:

Menjana dokumentasi mandiri untuk kod PHP, menghapuskan keperluan untuk menavigasi kod sumber secara langsung.
Pemasangan mudah melalui arkib atau komposer Phar.
Sangat boleh dikonfigurasikan melalui fail konfigurasi PHP, yang membolehkan penyesuaian tema, tajuk, membina direktori, dan caching.
menyokong tema tersuai dan kemasukan aset untuk rupa dan rasa yang diperibadikan.
mengintegrasikan dengan kawalan versi git, membolehkan dokumentasi untuk pelbagai versi kod.

Memahami DocBlocks:

DocBlocks adalah penting untuk Sami. Mereka adalah komen berbilang baris yang diletakkan di atas kelas, antara muka, kaedah, atau definisi atribut. Inilah contoh Laravel:

abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}

DocBlocks bermula dengan

, berakhir dengan /**, dan setiap baris dalam bermula dengan */. Anotasi seperti * dan @param memberikan maklumat tambahan. Piawaian anotasi phpdocumentor disokong secara meluas. @var

Sami vs Penjana Lain:

manakala penjana lain wujud (mis., Phpdocumentor), Sami menonjol kerana integrasi GitHub dan keupayaan templat twignya.

Memasang Sami:

Pilih salah satu kaedah ini:

1. Phar Archive: muat turun dan jalan sami.phar. php sami.phar
2. Komposer: Gunakan untuk menambah SAMI ke projek anda. Kemudian jalan composer require sami/sami:3.0.*. php vendor/sami/sami/sami.php

Menjana dokumentasi Laravel (contoh):

Klon Rangka Kerja Laravel:

1. git clone git@github.com:laravel/framework.git docs Buat fail
(lihat bahagian konfigurasi di bawah).
2. config/config.php run:
3. php vendor/sami/sami/sami.php update config/config.php
Konfigurasi (

):

config/config.php Fail ini mengembalikan contoh :

SamiSami Selepas menjalankan arahan kemas kini, mulakan pelayan PHP () dan akses dokumentasi di

.

$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

php -S localhost:8000 -t build/

versi git:

Sami cemerlang dalam mengendalikan pelbagai versi Git. Tambahkan pilihan versions ke konfigurasi anda:

abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}

ingat untuk memasukkan %version% dalam build_dir dan cache_dir.

Mewujudkan tema tersuai:

Sami membolehkan membuat tema tersuai. Letakkan fail manifest.yml dalam direktori tema anda (mis., ): themes/mytheme/manifest.yml

$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

Kemudian, ubah suai templat

untuk memasukkan CSS anda. Kemas kini fail konfigurasi anda untuk menggunakan tema tersuai anda: base.twig. Jalankan 'theme' => 'mytheme' untuk menjana semula dokumentasi. sami render config/config.php --force

Kesimpulan:

Sami menawarkan penyelesaian yang kuat dan fleksibel untuk menghasilkan dokumentasi API berkualiti tinggi untuk projek PHP anda. Cirinya, termasuk versi Git dan sokongan tema tersuai, menjadikannya alat yang berharga untuk mana -mana pemaju PHP. Contoh lengkap boleh didapati di GitHub (pautan akan ditambah di sini jika repo github wujud untuk contoh ini).

Atas ialah kandungan terperinci Menjana dokumentasi PHP dengan Sami. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!