Skip to content

Commit

Permalink
Tidy up docs:
Browse files Browse the repository at this point in the history 
Brings in the docca C++ doc stylesheet library in as a git submodule.
  • Loading branch information
@vinniefalco
vinniefalco committed Sep 27, 2016
1 parent 8ab8376 commit 40841eb
Show file tree
Hide file tree
Showing 15 changed files with 126 additions and 1,817 deletions.
3 changes: 3 additions & 0 deletions .gitmodules
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,6 @@
[submodule "extras/rocksdb"]
path = extras/rocksdb
url = https://github.com/facebook/rocksdb.git
[submodule "doc/docca"]
path = doc/docca
url = https://github.com/vinniefalco/docca.git
17 changes: 12 additions & 5 deletions doc/Jamfile → doc/Jamfile.v2
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@ using boostbook ;
using quickbook ;
using doxygen ;

xml bb : master.qbk ;

path-constant out : . ;

install stylesheets
Expand Down Expand Up @@ -47,14 +45,22 @@ install callouts

explicit callout ;

boostbook doc
xml doc
:
main.qbk
:
<location>temp
<include>$(broot)/tools/boostbook/dtd
;

boostbook boostdoc
:
bb
doc
:
<xsl:param>chapter.autolabel=0
<xsl:param>boost.image.src=images/logo.png
<xsl:param>boost.image.alt="NuDB Logo"
<xsl:param>boost.image.w=1600
<xsl:param>boost.image.w=1270
<xsl:param>boost.image.h=80
<xsl:param>boost.root=$(broot)
<xsl:param>chapter.autolabel=0
Expand All @@ -63,6 +69,7 @@ boostbook doc
<xsl:param>generate.section.toc.level=1 # Control depth of TOC generation in sections
<xsl:param>toc.max.depth=2 # How many levels should be created for each TOC?
<xsl:param>toc.section.depth=2 # How deep should recursive sections appear in the TOC?
<xsl:param>generate.toc="chapter nop section nop"
:
<location>temp
<dependency>stylesheets
Expand Down
1 change: 1 addition & 0 deletions doc/docca
Submodule docca added at 335dbf
Binary file modified doc/images/logo.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified doc/images/logo.psd
View file
Binary file not shown.
3 changes: 2 additions & 1 deletion doc/index.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->

<section id="index">
<section id="nudb.index">
<title>Index</title>
<index/>
</section>
66 changes: 46 additions & 20 deletions doc/master.qbk → doc/main.qbk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,36 @@
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']

[section Overview]
[variablelist
[[
[link nudb.overview Overview]
][
An overview of features, requirements, and credits, plus
rationale and design information.
]]
[[
[link nudb.example Example]
][
An example that illustrates the use of NuDB.
]]
[[
[link nudb.usage Usage]
][
An explanation of operations on the database.
]]
[[
[link nudb.ref Reference]
][
Detailed class and function reference.
]]
[[
[link nudb.index Index]
][
Book-style text index of the documentation.
]]
]

[section:overview Overview]

NuDB is an append only, key/value store specifically optimized for random
read performance on modern SSDs or equivalent high-IOPS decices. The most
Expand Down Expand Up @@ -117,7 +146,9 @@ database is created.

[endsect]

[section Example]


[section:example Example]

This complete program creates a database, opens the database, inserts several
key/value pairs, fetches the key/value pairs, closes the database, then erases
Expand Down Expand Up @@ -169,7 +200,9 @@ int main()

[endsect]

[section Usage]


[section:usage Usage]

[heading Files]

Expand All @@ -182,7 +215,7 @@ of a failure.

[heading Create/Open]

The [link nudb.ref.create create] function creates a new data file and key
The [link nudb.ref.nudb__create create] function creates a new data file and key
file for a database with the specified parameters. The caller specifies
the hash function to use as a template argument, the file paths,
and the database constants:
Expand Down Expand Up @@ -229,19 +262,19 @@ file.
The block size indicates the size of buckets in the key file. The best choice
for the block size is the natural sector size of the device. For most SSDs
in production today this is 4096, or less often 8192 or 16384. The function
[link nudb.ref.block_size block_size] returns the best guess of the block
[link nudb.ref.nudb__block_size block_size] returns the best guess of the block
size used by the device mounted at the specified path.

The load factor determines the target bucket occupancy fraction. There is
almost never a need to specify anything other than the recommended value of
0.5, which strikes the perfect balance of space-efficiency and fast lookup.

An open database is represented by objects of type
[link nudb.ref.basic_store basic_store], templated on the hasher. The type
alias [link nudb.ref.store store] represents a database using
[link nudb.ref.xxhasher xxhasher], the default hash function. To open
[link nudb.ref.nudb__basic_store basic_store], templated on the hasher. The type
alias [link nudb.ref.nudb__store store] represents a database using
[link nudb.ref.nudb__xxhasher xxhasher], the default hash function. To open
a database, declare a database object and then call the
[link nudb.ref.basic_store.open open] member function:
[link nudb.ref.nudb__basic_store.open open] member function:

```
store db;
Expand All @@ -263,7 +296,7 @@ db.insert(key, data, bytes, ec);
```

If the key already exists, the error is set to
[link nudb.ref.error.key_exists error::key_exists]. All keys in a NuDB
[link nudb.ref.nudb__error.key_exists error::key_exists]. All keys in a NuDB
database must be unique. Multiple threads can call insert at the same time.
Internally however, insertions are serialized to present a consistent view
of the database to callers.
Expand Down Expand Up @@ -298,19 +331,12 @@ nudb help

[endsect]


[section:types Type Requirements]
[section:ref Reference]
[xinclude quickref.xml]
[include types/File.qbk]
[include types/Hasher.qbk]
[include types/Progress.qbk]
[endsect]

[section:quickref Quick Reference]
[xinclude quickref.xml]
[endsect]

[include reference.qbk]
[endsect]

[section:idx Index]
[xinclude index.xml]
[endsect]
7 changes: 3 additions & 4 deletions doc/makeqbk.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@
# 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)

mkdir -p ../bin/doc/xml
mkdir -p temp
doxygen source.dox
cd ../bin/doc/xml
cd temp
xsltproc combine.xslt index.xml > all.xml
cd ../../../doc
xsltproc reference.xsl ../bin/doc/xml/all.xml > reference.qbk
xsltproc ../reference.xsl all.xml > ../reference.qbk
59 changes: 30 additions & 29 deletions doc/quickref.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,54 +25,55 @@
<entry valign="top">
<bridgehead renderas="sect3">Classes</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.ref.basic_store">basic_store</link></member>
<member><link linkend="nudb.ref.native_file">native_file</link></member>
<member><link linkend="nudb.ref.no_progress">no_progress</link></member>
<member><link linkend="nudb.ref.posix_file">posix_file</link></member>
<member><link linkend="nudb.ref.store">store</link></member>
<member><link linkend="nudb.ref.win32_file">win32_file</link></member>
<member><link linkend="nudb.ref.xxhasher">xxhasher</link></member>
<member><link linkend="nudb.ref.nudb__basic_store">basic_store</link></member>
<member><link linkend="nudb.ref.nudb__native_file">native_file</link></member>
<member><link linkend="nudb.ref.nudb__no_progress">no_progress</link></member>
<member><link linkend="nudb.ref.nudb__posix_file">posix_file</link></member>
<member><link linkend="nudb.ref.nudb__store">store</link></member>
<member><link linkend="nudb.ref.nudb__win32_file">win32_file</link></member>
<member><link linkend="nudb.ref.nudb__xxhasher">xxhasher</link></member>
</simplelist>
<bridgehead renderas="sect3">Constants</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.ref.errc">errc</link></member>
<member><link linkend="nudb.ref.error">error</link></member>
<member><link linkend="nudb.ref.file_mode">file_mode</link></member>
<member><link linkend="nudb.ref.nudb__errc">errc</link></member>
<member><link linkend="nudb.ref.nudb__error">error</link></member>
<member><link linkend="nudb.ref.nudb__file_mode">file_mode</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.ref.block_size">block_size</link></member>
<member><link linkend="nudb.ref.erase_file">erase_file</link></member>
<member><link linkend="nudb.ref.make_error_code">make_error_code</link></member>
<member><link linkend="nudb.ref.recover">recover</link></member>
<member><link linkend="nudb.ref.rekey">rekey</link></member>
<member><link linkend="nudb.ref.verify">verify</link></member>
<member><link linkend="nudb.ref.visit">visit</link></member>
<member><link linkend="nudb.ref.nudb__block_size">block_size</link></member>
<member><link linkend="nudb.ref.nudb__create">create</link></member>
<member><link linkend="nudb.ref.nudb__erase_file">erase_file</link></member>
<member><link linkend="nudb.ref.nudb__make_error_code">make_error_code</link></member>
<member><link linkend="nudb.ref.nudb__recover">recover</link></member>
<member><link linkend="nudb.ref.nudb__rekey">rekey</link></member>
<member><link linkend="nudb.ref.nudb__verify">verify</link></member>
<member><link linkend="nudb.ref.nudb__visit">visit</link></member>
</simplelist>
<bridgehead renderas="sect3">Type Traits</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.ref.is_File">is_File</link></member>
<member><link linkend="nudb.ref.is_Hasher">is_Hasher</link></member>
<member><link linkend="nudb.ref.is_Progress">is_Progress</link></member>
<member><link linkend="nudb.ref.nudb__is_File">is_File</link></member>
<member><link linkend="nudb.ref.nudb__is_Hasher">is_Hasher</link></member>
<member><link linkend="nudb.ref.nudb__is_Progress">is_Progress</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Types</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.ref.error_category">error_category</link></member>
<member><link linkend="nudb.ref.error_code">error_code</link></member>
<member><link linkend="nudb.ref.error_condition">error_condition</link></member>
<member><link linkend="nudb.ref.path_type">path_type</link></member>
<member><link linkend="nudb.ref.system_error">system_error</link></member>
<member><link linkend="nudb.ref.verify_info">verify_info</link></member>
<member><link linkend="nudb.ref.nudb__error_category">error_category</link></member>
<member><link linkend="nudb.ref.nudb__error_code">error_code</link></member>
<member><link linkend="nudb.ref.nudb__error_condition">error_condition</link></member>
<member><link linkend="nudb.ref.nudb__path_type">path_type</link></member>
<member><link linkend="nudb.ref.nudb__system_error">system_error</link></member>
<member><link linkend="nudb.ref.nudb__verify_info">verify_info</link></member>
</simplelist>
<bridgehead renderas="sect3">Concepts</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="nudb.types.File">File</link></member>
<member><link linkend="nudb.types.Progress">Progress</link></member>
<member><link linkend="nudb.types.Hasher">Hasher</link></member>
<member><link linkend="nudb.ref.File">File</link></member>
<member><link linkend="nudb.ref.Progress">Progress</link></member>
<member><link linkend="nudb.ref.Hasher">Hasher</link></member>
</simplelist>
</entry>
</row>
Expand Down
Loading

0 comments on commit 40841eb

Please sign in to comment.