Our Project

The GF2++ project is stored in a git repository the following structure:

Before we talk in more detail about the documentation we should mention that the library really has just two substantial headers Vector.h and Matrix.h. That assert.h is a short helper file defining macros used do optional assertions such as bounds checking primarily for debug builds. The library ha some headers than this but for the purposes of this discussion we will stick to those.

There is a convenience header GF2.h that just includes all the others. So, assuming your include path allows it, you use the library by just adding one line include <GF2/GF2.h> to the top of your program.

As you can see there are three separate modules in the docs/ directory:

The /docs/reference-manual/pages/ directory closely mimics the layout of the library source code in the /include/GF2/ directory. That pages/ directory looks somethings like:

The documentation is in the form of AsciiDoc files stored under the pages/ subdirectory. This layout makes it possible to easily use the static website builder Antora.

The pages/overview.adoc file introduces the library as a whole (this corresponds to the usual index.html for a website). Then each class and macro in GF2++ has a corresponding documentation sub-directory in pages/.

For example, the fairly trivial <GF2/assert.h> header just defines the three related assert style macros and those are all documented in the one assert.adoc file.

In contrast, the GF2::Vector and GF2::Matrix classes have a large number of associated methods and quite a few documentation files. Rather than having one documentation file per method we instead group methods and functions together where it logically makes sense for them to share a single file.

For example, the Vector/access.adoc file documents both GF2::Vector::operator()(i) methods, both GF2::Vector::operator[](i) methods, as well as the GF2::Vector::test(i) method. These are grouped together because each provides access to the individual element at a given index i in a bit-vector. The signature for each of the five is explained, how bounds checking can be enabled for the index, and the access.adoc file includes a short sample code that exercises the methods and the output from that code is shown. The user should be able to copy-paste that snippet, compile, and reproduce the shown results.

The main entry point for documenting the GF2::Vector class is the file Vector/Vector.adoc and for the GF2::Matrix class it is Matrix/Matrix.adoc. Those two files lay out the overall rationale behind the classes as well as providing links to all the other documentation in a nice table format.

The whole effect is quite similar to what you get if say you look up std::vector at CPP Reference/vector.

Expanding a little on our earlier picture the GF2++ repo now looks something like:

The top level docs/ directory is organized in a natural manner though we have made an effort to keep it compatible with the way Antora would like things. In particular, we have split the documentation into modules and then under each module stored the actual AsciiDoc content under a pages/ subdirectory, images under an images/ subdirectory and so on.

It does seem very sensible to keep the Antora specific parameter files, build instructions, needed support tools etc. in their own sandbox. In fact, the Antora documentation suggests having a completely separate repo for all that stuff. For a small library like ours that seems a bit of an overkill so instead we settled for having a dedicated antora/ directory at the top of the repo which looks like: