Bull Doc

Bulldoc outside home directory

It is common practice to put your docs in the same repository as code. Of course it is possible to work with this files simply by adding the book with absolute path to the bookshelf

/workshop/source/booshelf.yml

but in this case the amount of books on our bookshelf will grow to much. Anyway the absolute paths are evil.

Bulldoc gives the option to work with local bookshelves.

Let's review folder's structure in some abstract project:

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

  .htaccess
  index.php
  bookshelf.yml

snusmumrik_user_guide — is the docs source's folder and to compiled/snusmumrik_user_guide the export results will be placed. .htaccess contains request redirection to index.php, which in it's turn contains of just two lines:

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

bookshelf.yml — local bookshelf

file .htaccess should looks like this:

 
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]

If you're going to write some docs to your project, you should do the following steps:

It is convenient to place bulldoc's directory to environment PATH variable, or you have to type full path every time you use the program (windows, linux). Create doc directory inside your project's folder. Put .htaccess and index.php files there, if you are going to use web-interface. Run through the command line from the doc folder

bulldoc -c snusmumrik_user_guide

The necessary files will be created and a record will be added to the local bookshelf. Now is the time to write something.

The export to static html files is performed by calling

bulldoc snusmimrik_user_guide

The folder compiled will be created and the result files will be placed there.