modelspace::AutoDoc Class Reference

Class to document from code. More...

#include <AutoDoc.h>

Public Member Functions
	AutoDoc (unsigned int string_alloc=4096)
	Default constructor for the AutoDoc class.
	~AutoDoc ()
	Destructor – just closes our file.
int	file (const std::string &filename)
	Function to set the file for write and redirect output to that file.
std::string	file ()
int	title (const std::string &str)
	Function to write a title to the document.
int	author (const std::string &name, const std::string &email="")
	Function to write author name and email to document.
int	addPrimaryHeader (const std::string &str)
	Function to add a primary header to document.
int	addSecondaryHeader (const std::string &str)
	Function to add a secondary header to document.
int	addText (const std::string &str)
	Function to add an exact string to a document.
int	addImage (const std::string &file, const std::string &alias="")
	Function to add an image to the document.
int	addTable (const std::vector< std::vector< std::string > > &data, const std::vector< std::string > &col_headers={}, const std::vector< std::string > &row_headers={}, bool write_method=true)
	Function to write a table to our document.
int	addTable (const std::vector< std::vector< long int > > &data, const std::vector< std::string > &col_headers={}, const std::vector< std::string > &row_headers={}, bool write_method=true)
	Function to write a table to our document.
int	addTable (const std::vector< std::vector< double > > &data, const std::vector< std::string > &col_headers={}, const std::vector< std::string > &row_headers={}, bool write_method=true)
	Function to write a table to our document.
int	addCodeBlock (const std::string &str)
	Function to add a code block to a document.
int	addLink (const std::string &link, const std::string &alias="")
	Function to add an external link to the document.
int	addDocReference (const std::string &name, const std::string &alias="")
	Function to add a link to another asciidoc document.
void	closeFile ()
	Function to close the file held internally by AutoDoc.

Detailed Description

Class to document from code.

This class writes output from code, including strings, tables, images, and links, to an asciidoc document. It can write to a file specified by call to the file function, or to an internal string which can later be written to file.

The autodoc class is one of the most useful features of ModelSpace and allows users to generate an automated document from their analysis products easily and painlessly. It is extended into other languages, notably Python, via extensions implemented in those languages e.g. to integrate with matplotlib.

The generated document is in plaintext format, and needs to be rendered via asciidoctor or another document generation tool into HTML. Documents generated by autodoc (and, indeed, any .adoc file generated in the ModelSpace framework) can be previewed by pressing ctrl + shift + p with the .adoc file open, so long as appropriate extensions are installed.

Note

This module outputs errors to stdout and returns an error code, but does not exit on error so the rest of the document can generate, if the author wishes

Constructor & Destructor Documentation

AutoDoc()

modelspace::AutoDoc::AutoDoc

(

unsigned int

string_alloc = 4096

)

Default constructor for the AutoDoc class.

Parameters

(Optional)

The number of bytes to allocate for our buffering string. By default allocated 4 kB

Member Function Documentation

addCodeBlock()

int modelspace::AutoDoc::addCodeBlock

(

const std::string &

str

)

Function to add a code block to a document.

Parameters

str	The string to add to the code block

Returns

Success always

addDocReference()

int modelspace::AutoDoc::addDocReference	(	const std::string &	name,
		const std::string &	alias = ""
	)

Function to add a link to another asciidoc document.

Parameters

name	The name of the document to add
alias	Name the link will appear under – not used by default

Returns

Success always

addImage()

int modelspace::AutoDoc::addImage	(	const std::string &	file,
		const std::string &	alias = ""
	)

Function to add an image to the document.

Parameters

file	The image file to add
alias	The name the image will be added as – defaults to image

Returns

Success always

addLink()

int modelspace::AutoDoc::addLink	(	const std::string &	link,
		const std::string &	alias = ""
	)

Function to add an external link to the document.

Parameters

link	The link to add to the document
alias	Name the link will appear under – not used by default

Returns

Success always

addPrimaryHeader()

int modelspace::AutoDoc::addPrimaryHeader

(

const std::string &

str

)

Function to add a primary header to document.

Parameters

str	The header text

Returns

Succes always

addSecondaryHeader()

int modelspace::AutoDoc::addSecondaryHeader

(

const std::string &

str

)

Function to add a secondary header to document.

Parameters

str	The header text

Returns

Success always

addTable() [1/3]

int modelspace::AutoDoc::addTable	(	const std::vector< std::vector< double > > &	data,
		const std::vector< std::string > &	col_headers = {},
		const std::vector< std::string > &	row_headers = {},
		bool	write_method = true
	)

Function to write a table to our document.

Parameters

data	The data to write to the table
col_headers	The headers for each column. Default is empty (unused)
row_headers	The headers for each row. Default is empty (unused)
write_method	Flag to set whether data is organized by column (default) or row If column, then each vector element in data represents a column. If row, then each vector element represents a row.

Returns

Success always

Note

The necessary size of our column and row headers and data can vary based on configuration. If column or row headers are left empty, we will assume they aren't wanted and write data absent that element. So in a 5x5 table with row and column headers, we'd need 4x4 data. But if row headers were left empty, we'd need data to be 4x5 to match our headers. As a general rule, our table (headers + data) should make a nice, geometric shape.

addTable() [2/3]

int modelspace::AutoDoc::addTable	(	const std::vector< std::vector< long int > > &	data,
		const std::vector< std::string > &	col_headers = {},
		const std::vector< std::string > &	row_headers = {},
		bool	write_method = true
	)

Function to write a table to our document.

Parameters

data	The data to write to the table
col_headers	The headers for each column. Default is empty (unused)
row_headers	The headers for each row. Default is empty (unused)
write_method	Flag to set whether data is organized by column (default) or row If column, then each vector element in data represents a column. If row, then each vector element represents a row.

Returns

Success always

Note

The necessary size of our column and row headers and data can vary based on configuration. If column or row headers are left empty, we will assume they aren't wanted and write data absent that element. So in a 5x5 table with row and column headers, we'd need 4x4 data. But if row headers were left empty, we'd need data to be 4x5 to match our headers. As a general rule, our table (headers + data) should make a nice, geometric shape.

addTable() [3/3]

int modelspace::AutoDoc::addTable	(	const std::vector< std::vector< std::string > > &	data,
		const std::vector< std::string > &	col_headers = {},
		const std::vector< std::string > &	row_headers = {},
		bool	write_method = true
	)

Function to write a table to our document.

Parameters

data	The data to write to the table
col_headers	The headers for each column. Default is empty (unused)
row_headers	The headers for each row. Default is empty (unused)
write_method	Flag to set whether data is organized by column (default) or row If column, then each vector element in data represents a column. If row, then each vector element represents a row.

Returns

Success always

Note

The necessary size of our column and row headers and data can vary based on configuration. If column or row headers are left empty, we will assume they aren't wanted and write data absent that element. So in a 5x5 table with row and column headers, we'd need 4x4 data. But if row headers were left empty, we'd need data to be 4x5 to match our headers. As a general rule, our table (headers + data) should make a nice, geometric shape.

addText()

int modelspace::AutoDoc::addText

(

const std::string &

str

)

Function to add an exact string to a document.

Parameters

str	The string to add

Returns

Success always

author()

int modelspace::AutoDoc::author	(	const std::string &	name,
		const std::string &	email = ""
	)

Function to write author name and email to document.

Parameters

name	The author's name
email	The author's email. Defaults to nothing

Returns

0 on successful title write, 1 if author cannot be written

Note

Author can only be written at the start of a document after title is written. If title is not written or anything after title has been written, will return error.

file()

int modelspace::AutoDoc::file

(

const std::string &

filename

)

Function to set the file for write and redirect output to that file.

Parameters

filename

The filename to write to

Returns

0 on success, 1 on failure

Note

Calling this function will cause the AutoDoc class to begin writing its data to the provided file

title()

int modelspace::AutoDoc::title

(

const std::string &

str

)

Function to write a title to the document.

Parameters

str	The document title

Returns

0 on successful title write, 1 if title cannot be written

Note

Title can only be written at the start of a document. Once other stuff has been written, title is locked and will return error.

---

The documentation for this class was generated from the following files:

• /home/mickey/modelspace/cpp/src/utils/AutoDoc.h
• /home/mickey/modelspace/cpp/src/utils/AutoDoc.cpp