Docs orgainzation proposal
A standard layout for our docs files.
Table of contents
Docs files Organization
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).
Docs files examples
Examples list
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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></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"><<</phrase> <phrase role="string">"Hello, World\n"</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>
Last modified
15 years ago
Last modified on Jul 14, 2007, 12:46:32 PM
Note:
See TracWiki
for help on using the wiki.
