phpDocumentor

’tag’

PHPDoctor вместо phpDocumentor

Май 28, 2012

После того, как я попробовал использовать PHPDoctor, то теперь однозначно буду использовать только его. Почему решил попробовать? Ответ простой: меня интересовало включение исходного кода файлов, которые документируются, phpDocumentor версии 1.4.4 не мог справиться с задачей, а PHPDoctor справляется отлично.

Установка PHPDoctor

PHPDoctor ставится просто. Сначала его нужно скачать:

Далее распаковать в любом месте. Я распаковал его в папку phpdoctor, которую создал в папке с локальным сервером:
/var/www/phpdoctor

Помещать его в папку с локальным сервером не обязательно. Для меня это способ всегда знать, где он находится.

Все, установка завершена. В отличие от phpDocumentor – это невероятно простой способ.

Использование PHPDoctor

Перед использованием в папке с PHPDoctor создается файл настроек с расширением ini и любым именем. Например:
myconfig.ini

После создания копируем туда содержимое файла default.ini и меняем необходимые настройки.

Список параметров с описанием можно посмотреть на странице:

В принципе в файле default.ini они и так достаточно хорошо описаны.

После сохраняем файл myconfig.ini и выполняем команду в Терминале:

php phpdoc.php myconfig.ini

Перед выполнением команды нужно перейти в папку с PHPDoctor из Терминала:

cd /var/www/phpdoctor/

В папке, которая была указана в файле настроек myconfig.ini для сохранения документации, появятся файлы.

Особенности PHPDoctor

Как я уже сказал, PHPDoctor отлично справляется с задачей указания ссылок на файлы и отображение их исходного кода.

Подсветка синтаксиса в PHPDoctor

Для того, чтобы в исходном коде файлов работала подсветка синтаксиса необходимо скачать GeSHi и поместить его в папку с PHPDoctor:

Директивы файла конфигурации

files – Names of files to parse. This can be a single filename, or a comma separated list of filenames. Wildcards are allowed.

ignore – Names of files or directories to ignore. This can be a single filename, or a comma separated list of filenames. Wildcards are NOT allowed.

source_path – The directory to look for files in, if not used the PHPDoctor will look in the current directory (the directory it is run from).

subdirs – If you do not want PHPDoctor to look in each sub directory for files uncomment this line.

quiet – Set how loud PHPDoctor is as it runs. Quiet mode suppresses all output other than warnings and errors.

verbose – Set how loud PHPDoctor is as it runs. Verbose mode outputs additional messages during execution.

doclet – Select the doclet to use for generating output.

doclet_path – The directory to find the doclet in. Doclets are expected to be in a directory named after themselves at the location given.

taglet_path – The directory to find taglets in. Taglets allow you to make PHPDoctor handle new tags and to alter the behavour of existing tags and their output.

default_package – If the code you are parsing does not use package tags or not all elements have package tags, use this setting to place unbound elements into a particular package.

overview – Specifies the name of a HTML file containing text for the overview documentation to be placed on the overview page. The path is relative to "source_path" unless an absolute path is given.

package_comment_dir – Package comments will be looked for in a file named package.html in the same directory as the first source file parsed in that package or in the directory given below. If package comments are placed in the directory given below then they should be named ".html".

globals – Parse out global variables.

constants – Parse out global constants.

private – Generate documentation for all class members.

protected – Generate documentation for public and protected class members.

public – Generate documentation for only public class members.

d – The directory to place generated documentation in. If the given path is relative to it will be relative to "source_path".

windowtitle – Specifies the title to be placed in the HTML.

doctitle – Specifies the title to be placed near the top of the overview summary file.

header – Specifies the header text to be placed at the top of each output file. The header will be placed to the right of the upper navigation bar.

footer – Specifies the footer text to be placed at the bottom of each output file. The footer will be placed to the right of the lower navigation bar.

bottom – Specifies the text to be placed at the bottom of each output file. The text will be placed at the bottom of the page, below the lower navigation bar.

tree – Create a class tree.

Tags: , , , ,
Записано в Ubuntu, Программирование    |    Постоянная ссылка

Установка phpDocumentor в Ubuntu 10 и связанные проблемы

Май 28, 2012

Если ранее PhpDocumentor не был установлен в Ubuntu 10, то проблем не возникнет.

Поиск в Интернете позволил мне найти очень хорошую статью на эту тему на английском:

Прежде установки самого phpDocumentor следует установить LAMP. Как это сделать хорошо написано в данной статье:

Установка LAMP

Приведу пример установки Apache + PHP 5 версии + MySQL + PhpMyAdmin. Далее команды терминала:

apt-get update
aptitude install apache2 php5 libapache2-mod-php5
aptitude install mysql-server mysql-client php5-mysql
apt-get install phpmyadmin

Если команды с префиксом "aptitude" не работают, то можно элементарно открыть Менеджер пакетов Synaptic и в ручную найти, отметить для установки и установить следующие компоненты:

  • apache2
  • php5
  • libapache2-mod-php5

После установить:

  • mysql-server
  • mysql-client
  • php5-mysql

И в завершение:

  • phpmyadmin

В процессе установки будет предложено задать пароль для MySQL и PhpMyAdmin, если не ошибаюсь. Желательно использовать один и тот же пароль в обоих случаях во избежание путаницы.

После открываем следующий файл:
/etc/apache2/apache2.conf

и в любое место вставляем строку:
Include /etc/phpmyadmin/apache.conf

Останавливаем и вновь запускаем Apache:

sudo /etc/init.d/apache2 stop
sudo /etc/init.d/apache2 start

Можно пробовать открыть следующий адрес:

PhpMyAdmin доступен по адресу:

Установка phpDocumentor

Теперь что касается непосредственно установки phpDocumentor:

sudo apt-get install php-pear
sudo pear config-set data_dir /var/www
sudo pear install --alldeps PhpDocumentor

phpDocumentor установлен. Теперь осталось задать папку, где будут храниться папки документации:

sudo mkdir /var/www/PhpDocumentor-output
sudo chown www-data /var/www/PhpDocumentor-output

Документацию можно сформировать через Терминал:

phpdoc --output HTML:frames:DOM/earthli --directory /var/www/joomla17/ --target /var/www/PhpDocumentor-output/joomla17/ --title 'Joomla 1.7' --defaultpackagename 'Joomla' --defaultcategoryname 'Joomla' --parseprivate on --sourcecode on

Список параметров и описания к ним можно отобразить в Терминале с помощью команды:

phpdoc -h

Описания параметров и примеры использования phpDocumentor можно найти на этой странице:

Проблемы при установке phpDocumentor

Сегодня я уже сделал одну большую ошибку, решив установить phpDocumentor версии 2. Сломалась, как версия 1.4.4, так и 2 не стала работать.

Еще ранее я нечаянно удалил папку с phpDocumentor:
/var/www/PhpDocumentor

Если пробовать заново установить phpDocumentor по схеме, указанной выше, то ничего не получится. Для того, чтобы решить проблему сначала нужно скачать оригинальные файлы от версии 1.4.4:

На странице по ссылке нужно сверху нажать на ссылку "Download PhpDocumentor-1.4.4.zip". Затем распаковать архив на компьютере и перенести его в папку:
/var/www/PhpDocumentor

Если же была неудачная попытка установить phpDocumentor2, то необходимо:

  • удалить папки:
    • /var/www/PhpDocumentor
    • /usr/share/php/PhpDocumentor
    • /usr/share/php/PEAR
  • удалить файл:
    • /usr/bin/phpdoc

После этого через виртуальную машину Oracle VM VirtualBox или на другой компьютер установить Ubuntu 10 и поставить на него phpDocumentor 1.4.4. Затем скопировать папки и файл, который мы удалили ранее. Все должно работать.

Что касается phpDocumentor2, то более даже не буду пробовать его установить.

Изначально скачал phpDocumentor2 здесь:

Потом скопировал его в папку /var/www/phpDocumentor2. Затем запустил installer.php. Не помню, но вроде ничего не произошло.

Увидел рекомендации разработчиков по установке. Выполнил в Терминале 2 команды:

pear channel-discover pear.phpdoc.org
pear install phpdoc/phpDocumentor-alpha

После этого более ни одна из версий phpDocumentor не работала и пришлось все восстанавливать несколько часов.

Tags: , , ,
Записано в Ubuntu    |    Постоянная ссылка