Write docs with boost quickbook

Boost quickbook and boostbook are very good to generate html, pdf, man documents. Boost quickbook .qbk file format is good to write.

Requires:

Build and Install B2 Build
Build and Install Boost Docs System: boost quickbook

boost quickbook: Write Simple Docs

First: Init project folders

Init project folders:

> mkdir foo
> cd foo

Next: Write a start .qbk file

File: main.qbk

[book c++ Book
	[id cpp-book]
	[quickbook 1.7]
]

Start, c++

[h1:cpp Hello World!]

Hello, c++

Thanks, website [@https://cppfx.xyz cppfx]

As you see, you will quickly understand .qbk file syntax.

The title is c++ Book, and the html tag <h1> will use the title as header too.

The [h1 will be used as html <h2>

To avoid keyword c++ to parsed as c, let it to be parsed as cpp, define id anywhere.
For example, document id:

c++ Book [id cpp-book]

For example, anchor id:

[h1:cpp-text c++ text]

Then c++ will be parsed as cpp

Next: Write Jamfile

File: jamroot

xml abc : main.qbk ;

boostbook xyz : abc ;

The rule xml defines a target abc, so it will generate file abc.xml

The rule boostbook defines a target xyz, and use previous target abc as its source, it will generate files abc.docook, index.html

A .qbk file refered in the jamfile will generate the html index file: index.html;
A .qbk file refered in another .qbk file will generate a html subpage, not index.
Read below.

Next: Build at the first time

Just run command b2:

> b2

You will see the html document is generated.

Next: Add another qbk, for subpage

File: cpp-article.qbk

[article This is c++ subpage title
	[id cpp-subpage]
	[quickbook 1.7]
]

Hello, c++ World!

This is c++ document

[h1:cpp-text c++ Text]

Hi, I a room.

Add subpage to the main page

A subpage is not written to the jamfile, but written to the main .qbk file: main.qbk

The updated main.qbk will be like this:

[book c++ Book
	[id cpp-book]
	[quickbook 1.7]
]

[include cpp-article.qbk]

Start, c++

[h1 Hello World!]

Hello, c++

Thanks, website [@https://cppfx.xyz cppfx]

Next: Build Again

> b2

Next: Install boost media

The html generated above is not so nice-looking, thats because boost media is not installed.

Extract boost c++ library release package, then add the following code to jamroot :

(Please replace my-path/to-extracted/boost-release with your real boost extracted folder path.)

boost-path = my-path/to-extracted/boost-release ;
boost-media-path = $(boost-path)/doc/src ;

install
	boost-media
:
	[
		glob
			$(boost-media-path)/*.css
			$(boost-media-path)/images/*.png
	]
:
	<location>./html
	<install-source-root>$(boost-media-path)
;

The rule install defines a target boost-media, and use the files of searched by [ glob ... ] as its sources, copy the files to location ./html/

install-source-root :

Without this property, the css and png files will be installed under ./html/my-path/to-extracted/boost-release/doc/src/
With this property, the css and png files will be installed under ./html/

Next: Build again

> b2