Bulldoc вне родной директории

Обычно в процессе разработки исходники документации лежат в репозитории проекта рядом с кодом. Можно было бы работать с этими файлами, добавив книгу в файл основной книжной полки

/workshop/source/booshelf.yml

однако в таком случае количество книжек на нашей основной полке со временем станет слишком большим, а учитывая всякие вариации вывода, вообще может превратить полку в помойку.

Bulldoc дает возможность работать с файлами документации из директорий проектов.

Рассмотрим структуру папок документации, в абстрактном проекте:

/snusmumrik/doc
  /snusmumrik_user_guide
  /snusmumrik_developer_guide
  /compiled
    /snusmumrik_user_guide
    /snusmumrik_developer_guide

  .htaccess
  index.php
  bookshelf.yml

snusmumrik_user_guide — это папка с исходниками книги, а в compiled/snusmumrik_user_guide будут складываться результаты экспорта. .htaccess содержит перенаправление запросов на index.php, который, в свою очередь, состоит из двух строчек:

 
set_include_path('.');
require('/path/to/bulldoc/index.php');

bookshelf.yml — локальная книжная полка

файл .htaccess должен выглядеть так:

 
Options FollowSymLinks
 
RewriteEngine On
 
#General config
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule ^(.+)$ index.php?colesoRequestPath=$1 [L,QSA]

Если Вы собрались писать документацию к Вашему проекту, то можно проделать следующие действия:

Чтобы не указывать полный путь к программе, добавьте путь к bulldoc к переменной окружения PATH (windows, linux). Создайте папку doc внутри проекта. Поместите туда файлы .htaccess и index.php, если хотите пользоваться веб-интерфейсом. В командной строке из папки doc запустите


bulldoc -c snusmumrik_user_guide

Будут созданы заготовки для книги и запись в книжной полке. Можно начинать писать.

Чтобы сделать экспорт в статику запустите


bulldoc snusmimrik_user_guide

Будет создана папка compiled, куда программа поместит результат.

Bull Doc

Bulldoc вне родной директории