DocsOrganization – Boost C++ Libraries

Context Navigation

← Previous Version
View Latest Version
Next Version →

Version 1 (modified by Matias Capeletto, 15 years ago) ( diff )
--

Docbook source - Required

doc/lib_name.xml
Doc source in docbook format. Optionally it can include boostbook extensions.
doc/lib_name.xsl
Library dependents output configuration parameters (i.e. chunker depth).
doc/Jamfile.v2
"doc/bjam --v2" will generate the HTML docs.

Quickbook Source - Optional

doc/lib_name.qbk
Main quickbook file.
doc/*.qbk
Moderate size main sections quickbook files
doc/larger_section.qbk
doc/larger_section/*.qbk
Large size main sections (i.e reference) may be splitted again, organizing them in a directory tree to avoid cluttering the doc directory.

Images - Optional

doc/images/*.png
You can use other formats, but be a good web citizen and use portable networks graphics.
doc/images/*.svg
If you intend to have a decent rendering in the pdf docs, use svg.

Examples - Optional

example/doc/*.cpp
Quickbook allows us to import code chunks, instead of hard-coding them in the qbk source. This allow as to be sure that every code example will be in sync and with out typos.
example/doc/Jamfile.v2
Testsuite for the doc examples.

Navigation aid - Will be automated in the future

doc/html/sections.xml
Nested links xml definition of the library sections. This file is used to generate the navigation select boxes and tree sidebar (expected it soon).

Library docs organization example

Examples list

Docbook source
Quickbook Source
1. doc/lib_name.qbk
2. doc/moderate_section.qbk
Doc Examples
Navigation aid
1. doc/html/sections.xml

Docbook source

doc/lib_name.xml

Doc source in docbook format. Optionally it can include boostbook extensions.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library id="library_name" name="Boost.LibraryName" dirname="library_name" last-revision="$Date: 2007/06/14 22:18:40 $"
 xmlns:xi="http://www.w3.org/2001/XInclude">

  <libraryinfo>
    <author>
      <firstname>name</firstname> <surname>name</surname>
    </author>
    <copyright>
      <year>year</year> <holder>name</holder>
    </copyright>
    <legalnotice>
      <para>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at 
        <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)
      </para>
    </legalnotice>
    <librarypurpose>
      Standard boostbook example
    </librarypurpose>
    <librarycategory name="category:library_category"></librarycategory>
  </libraryinfo>

  <title>Boost.LibraryName</title>

  <section id="library_name.section_id">

    <title>Section Title</title>

    <para>
      This is an example of a <emphasis role="bold">standard</emphasis> Boostbook document. 
      An <ulink url="http://www.boost.org">external link</ulink>
    </para>

    <para>
      These should be syntax highlighted:
    </para>
  
    <programlisting>
<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>

<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
<phrase role="special">{</phrase>
    <phrase role="comment">// Sample code
</phrase>    <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;Hello, World\n&quot;</phrase><phrase role="special">;</phrase>
    <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase>

    </programlisting>

  </section>

</library>

doc/lib_name.xsl

Library dependents output configuration parameters (i.e. chunker depth).

<?xml version="1.0" encoding="utf-8"?>
<!--
   Copyright (c) Year author name, author name

   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
   http://www.boost.org/LICENSE_1_0.txt)
                                                                   -->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

  <!-- HTML Boostbook parameters -->

  <xsl:param name = "chapter.logo.img"             select = "'../images/library_logo.png'" />

  <xsl:param name = "quickbook.source.style.show"  select = "'true'" />

  <!-- HTML Dockbook parameters -->

  <xsl:param name = "chunk.section.depth"          select = "2" />

</xsl:stylesheet>

doc/Jamfile.v2

"doc/bjam --v2" will generate the html docs.

# Boost.LibraryName
#
# Copyright (c) Years author name, author name
#
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)

using quickbook ;

xml library_name 
    : 
        library_name.qbk ;


boostbook standalone
    :
        library_name
    :
        library_name.xsl
    ;

Quickbook Source

doc/lib_name.qbk

Main quickbook file.

[library LibraryName
    [quickbook 1.4]
    [copyright Year author name, author name]
    [purpose Standard qbk example]
    [id library_name]
    [dirname library_name]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [http://www.boost.org/LICENSE_1_0.txt])
    ]
    [authors [surname, firstname], [surname, firstname] ]
    [category library_category]
]

[/ Templates ]

[/ Images ]

[template Diagram [$../images/diagram.png]]

[/ External Links ]

[template SgiAssignable [@http://www.sgi.com/tech/stl/Assignable.html Assignable]]

[/ Sections ]

[section Small Section]

A few lines.
A nice diagram of the lib:
[Diagram]

[endsect]

[/ Moderate section abstract ]
[include moderate_size_section.qbk]

[/ Larger section abstract ]
[include larger_size_section.qbk]

[section Other Small Section]

Some more lines.
An external resource: [SgiAssignable]

[endsect]

doc/moderate_section.qbk

Moderate size main sections quickbook files

[/
    Boost.LibrayName
    Copyright (c)  Year author name

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]

[/ QuickBook Document version 1.4 ]

[/ Section specifics templates ]

[template ModerateSizeImage [$../images/moderate_size_image.svg]

[/ Sections ]

[section Moderate section]

You can use this sections templates to show an image:
[ModerateSizeImage]

Main templates are allowed too, reuse [SgiAssignable].

A nice table, including marketting stuff

[table Quickbook Rocks

[[Feature              ][Purpose                                   ]]

[[Templates            ][Extensibility and constants               ]]
[[Code import          ][Code consistency, callouts and reuse      ]]
[[Wiki style formating ][High signal to noise ratio in source code ]]
[[Internal links       ][Easy to use inter-doc anchors             ]]
[[Syntax Highlighting  ][Both in code blocks and in `inline code`  ]]

]

[endsect]

Doc Examples

example/doc/code_example.cpp

Quickbook allows us to import code chunks, instead of hard-coding them in the qbk source. This allow as to be sure that every code example will be in sync and with out typos.

// Boost.LibraryName
//
// Copyright (c) Year author name, author name
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)

// Doc example

#include <string>
#include <iostream>

//[ DocCodeFunctionName

std::string greeting()
{
    return "Hello world!";
}

//]

//[ DocCodeExampleName

int main()
{
    /*<< A callout bug >>*/
    std::string message = greeting();
    std::cout << message; /*< Inlined callout bug >*/
}

//]

doc/larger_section.qbk

[/
    Boost.LibrayName
    Copyright (c) Year author name

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]

[/ QuickBook Document version 1.4 ]

[/ Section specifics code ]

[import ../example/doc/example_name.cpp]

[/ Sections ]

[section Larger section]

[section Introduction]

A few lines.
We can easily use the imported code:

[DocCodeFunctionName]

And then the main function

[DocCodeExampleName]

That is it!

[endsect]

[include larger_section/subsection_name.qbk]

[endsect]

example/doc/Jamfile.v2

Testsuite for the doc examples.

# Boost.LibraryName
#
# Copyright (c) Years author name, author name
#
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)

import testing ;

test-suite "doc_code"
    :
    [ compile       compilable_example.cpp      ]
    [ run           runable_example.cpp         ]
    [ compile-fail  compile_fail_example.cpp    ]
    ;

Navigation aid

doc/html/sections.xml

Nested links xml definition of the library sections. This file is used to generate the navigation select boxes and tree sidebar (expected it soon'').

<?xml version="1.0" encoding="UTF-8" ?>

<!--
    Boost.LibraryName Sections

    Copyright (c) Year author name, author name

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
                                                                           -->

<nestedLinks version="1.0">

    <title tag="Sections"                     href="index.html" />

    <link tag="Introduction"                  href="library_name/introduction.html" />
    <link tag="Moderate size section"         href="library_name/moderate_section.html" >
        <link  tag="First Subsection"         href="library_name/moderate_section/first_subsection.html" />
        <link  tag="Second Subsection"        href="library_name/moderate_section/second_subsection.html" />
        <link  tag="Last Subsection"          href="library_name/moderate_section/last_subsection.html" />
    </link>
    <link  tag="Larger size section"          href="library_name/larger_section.html" >
        <link  tag="First Subsection"         href="library_name/larger_section/first_subsection.html" />
        <link  tag="Second Subsection"        href="library_name/larger_section/second_subsection.html" >
            <link  tag="Deeper section"       href="library_name/.../deeper_section.html" />
        </link>
        <link tag="Last Subsection"           href="library_name/larger_section/last_subsection.html" />
    </link>
    <link  tag="Acknowledgments"              href="library_name/acknowledgments.html" />

</nestedLinks>

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text