Skip to content
This repository has been archived by the owner on Mar 19, 2021. It is now read-only.

Commit

Permalink
some improvements for autodoc
Browse files Browse the repository at this point in the history 
better resource data type handling,
resource name converted from CamelCase to space separated form,
boolean default values converted from "true/false" to "yes/no" to correspond the rest of the documentation
  • Loading branch information
@joergsteffens
joergsteffens committed Oct 10, 2014
1 parent 79b2e50 commit 25a1f20
Show file tree
Hide file tree
Showing 6 changed files with 87 additions and 25 deletions.
2 changes: 1 addition & 1 deletion manuals/en/main/bareos-manual-main-reference.tex
View file
Expand Up @@ -48,7 +48,7 @@
\usepackage{textcomp}

% \ifcsdef: check if a label is defined
%\usepackage{etoolbox}
\usepackage{etoolbox}

\usepackage{bareos}

Expand Down
37 changes: 28 additions & 9 deletions manuals/en/main/bareos.sty
View file
Expand Up @@ -34,33 +34,52 @@
% data type definitions.
% all data types should be defined here.
% use them in xdirective.
\newcommand{\dtAcl}{\ilink{acl}{DataTypeNetAcl}}
\newcommand{\dtAddress}{\ilink{net-address}{DataTypeNetAddress}}
\newcommand{\dtAddresses}{\ilink{net-addresses}{DataTypeNetAddresses}}
\newcommand{\dtAutopassword}{\ilink{password}{DataTypePassword}}
\newcommand{\dtBoolean}{\ilink{\yesno}{DataTypeYesNo}}
\newcommand{\dtDirectory}{\ilink{directory}{DataTypeDirectory}}
\newcommand{\dtName}{\ilink{name}{DataTypeName}}
\newcommand{\dtNetAddress}{\ilink{net-address}{DataTypeNetAddress}}
\newcommand{\dtNetAddresses}{\ilink{net-addresses}{DataTypeNetAddresses}}
\newcommand{\dtNetPort}{\ilink{net-port}{DataTypeNetPort}}
\newcommand{\dtPassword}{\ilink{password}{DataTypePassword}}
\newcommand{\dtPath}{\ilink{path}{DataTypePath}}
\newcommand{\dtPositiveInteger}{\ilink{positive-integer}{DataTypePositiveInteger}}
\newcommand{\dtUInt}{\dtPositiveInteger}
% use csdef instead of newcommand, because command contains numbers
\csdef{dtPint32}{\dtUInt}
\newcommand{\dtRes}{\ilink{resource-name}{DataTypeRes}}
\newcommand{\dtPort}{\dtNetPort}
\newcommand{\dtSize}{\ilink{size}{DataTypeSize}}
\newcommand{\dtString}{\ilink{string}{DataTypeString}}
\newcommand{\dtStringList}[1]{\ilink{string-list (separated by #1)}{DataTypeStringList}}
\newcommand{\dtStringList}{\ilink{string-list}{DataTypeStringList}}
\newcommand{\dtTime}{\ilink{time}{DataTypeTime}}
\newcommand{\dtUInt}{\ilink{positive-integer}{DataTypePositiveInteger}}
\newcommand{\dtYesNo}{\ilink{\yesno}{DataTypeYesNo}}

\newcommand{\dt}[1]{\path|#1|}
\newcommand{\dt}[1]{%
\ifcsdef{dt#1}{\csuse{dt#1}}{\path|#1|} %
}

%
% references
%

%%
% 1: text, 2: URL
\newcommand*{\elink}[2]{%
\htmladdnormallink{#1}{#2}%
%\htmladdnormallink{#1}{#2}%
\href{#2}{#1}%
}
%%
% or use \url{URL}

% 1: text, 2. URL
\newcommand*{\ilink}[2]{%
\htmlref{#1}{#2}%
%\htmlref{#1}{#2}%
\hyperref[#2]{#1}%
}
%%
% or use \autoref{label} (or \nameref{label}


\newcommand{\dq}{\verb+"+}
\newcommand{\at}{\makeatletter @\makeatother}
\newcommand{\lt}{\textless}
Expand Down
20 changes: 19 additions & 1 deletion manuals/en/main/configure.tex
View file
Expand Up @@ -185,6 +185,18 @@ \subsection{Data Types}
\begin{description}
\item [acl]
\index[general]{Data Type!acl}
\label{DataTypeAcl}
This directive defines what is premitted to access.
It does this by a list of strings, separated by \parameter{,}.
The special keyword \parameter{*all*} allows unrestricted access.
Depending on the type of the ACL, the strings can by either resource names, paths or bconsole commands.
\item [directory]
\index[general]{Data Type!directory}
\label{DataTypeDirectory}
Expand Down Expand Up @@ -314,6 +326,11 @@ \subsection{Data Types}
\label{DataTypeNetPort}
Specify a network port (a positive integer).
\item [resource]
\index[general]{Data Type!resource}
\label{DataTypeRes}
A resource defines a relation to the name of another resource.
\item [size]
\index[general]{Data Type!size}
Expand Down Expand Up @@ -412,8 +429,9 @@ \subsection{Data Types}
\item [\yesno]
\index[general]{Data Type!\yesno}
\index[general]{Data Type!boolean}
\label{DataTypeYesNo}
Either a {\bf yes} or a {\bf no}.
Either a \parameter{yes} or a \parameter{no} (or \parameter{true} or \parameter{false}).
\end{description}
Expand Down
6 changes: 3 additions & 3 deletions manuals/en/main/consoleconf.tex
View file
Expand Up @@ -205,11 +205,11 @@ \section{Console Resource}
\item [HistoryFile = {\textless}history-file-name{\textgreater}] \hfill \\
If this directive is specified and the console is compiled with readline support,
it will use the given filename as history file.
If not specified, the history file will be named \bf{~/.bconsole\_history}
If not specified, the history file will be named \file{~/.bconsole_history}

\item [HistoryLength = {\textless}number{\textgreater}] \hfill \\
If this directive is specified the history file will be tuncated after \bf{HistoryLength} enries.
If not specified, the default value for the history length is \bf{100} entries.
If this directive is specified the history file will be tuncated after \configdirective{HistoryLength} enries.
If not specified, the default value for the history length is \parameter{100} entries.



Expand Down
4 changes: 2 additions & 2 deletions manuals/en/main/dirdconf.tex
View file
Expand Up @@ -146,7 +146,7 @@ \section{Director Resource}
defines, how these messages are handled.
}

\xdirective{dir}{Audit Events}{\dtStringList{,}}{}{}{14.2}{%
\xdirective{dir}{Audit Events}{\dtStringList}{}{}{14.2}{%
}


Expand Down Expand Up @@ -298,7 +298,7 @@ \section{Director Resource}
only the specified plugins get loaded.
}

\directive{dir}{Plugin Names}{\dtStringList{:}}{}{}{14.2}%{%
\directive{dir}{Plugin Names}{\dtStringList}{}{}{14.2}%{%
If a \configdirective{Plugin Directory} is specified
\configdirective{Plugin Names} defines, which \ilink{Director plugins}{dirPlugins} get loaded.

Expand Down
43 changes: 34 additions & 9 deletions manuals/scripts/generate-resoure-descriptions.py
View file
Expand Up @@ -4,6 +4,7 @@
import logging
import json
from pprint import pprint
import re
import sys

class BareosConfigurationSchema:
Expand All @@ -25,8 +26,25 @@ def getResourceDirective(self, resourcename, directive, deprecated=None):
# None: include deprecated
# False: exclude deprecated
# True: only deprecated
return self.json[resourcename][directive]
return BareosConfigurationSchemaDirective( self.json[resourcename][directive] )

class BareosConfigurationSchemaDirective(dict):
def getDefaultValue( self ):
default=None
if dict.get( self, 'default_value' ):
if dict.get( self, 'default_value' ) == "true":
default="yes"
elif dict.get( self, 'default_value' ) == "false":
default="no"
else:
default=dict.get( self, 'default_value' )
return default

def get( self, key ):
if key == "default_value" or key == "default":
return self.getDefaultValue()
else:
return dict.get(self,key)

class BareosConfigurationSchema2Latex:
def __init__( self, json ):
Expand Down Expand Up @@ -61,12 +79,20 @@ def getStringsWithModifiers(self, text, strings):
else:
return ""

def convertCamelCase2Spaces( self, valueCC ):
s1 = re.sub('([a-z0-9])([A-Z])', r'\1 \2', valueCC)
#return s1
result=[]
for token in s1.split(' '):
u = token.upper()
if u in [ "ACL", "CA", "CN", "DB", "DH", "FD", "NDMP", "SD", "TLS", "VSS" ]:
token=u
result.append(token)
return " ".join( result )

def getLatexDatatypeRef( self, datatype ):
DataType="".join([x.lower().capitalize() for x in datatype.split('_')])
if DataType == "StringList":
return "\\ifdefined\\dt%(DataType)s \\dt%(DataType)s{,} \\else \\dt{%(DataType)s} \\fi" % { 'DataType': DataType }
else:
return "\\ifdefined\\dt%(DataType)s \\dt%(DataType)s \\else \\dt{%(DataType)s} \\fi" % { 'DataType': DataType }
return "\\dt{%(DataType)s}" % { 'DataType': DataType }

def getResourceDirectivesTable(self, resourcename):
result="\\begin{center}\n"
Expand All @@ -77,7 +103,7 @@ def getResourceDirectivesTable(self, resourcename):
data=self.schema.getResourceDirective(resourcename, directive)

strings={
'directive': directive,
'directive': self.convertCamelCase2Spaces( directive ),
'mc': "}",
'extra': [],
'default': "",
Expand All @@ -87,7 +113,7 @@ def getResourceDirectivesTable(self, resourcename):
if data.get( 'equals' ):
strings["datatype"]="= %(datatype)s" % { 'datatype': strings["datatype"] }
else:
strings["datatype"]="{ %(datatype)s }" % { 'datatype': strings["datatype"] }
strings["datatype"]="\{ %(datatype)s \}" % { 'datatype': strings["datatype"] }

extra=[]
if data.get( 'alias' ):
Expand Down Expand Up @@ -134,7 +160,7 @@ def getResourceDirectives(self, resourcename):
for directive in self.schema.getResourceDirectives(resourcename):
data=self.schema.getResourceDirective(resourcename, directive)

datatype="\\dt{"+data['datatype']+"}"
datatype="\\dt{"+data.get('datatype')+"}"
deprecated=""
if data.get( 'deprecated' ):
deprecated="deprecated"
Expand All @@ -144,7 +170,6 @@ def getResourceDirectives(self, resourcename):
default=""
if data.get( 'default_value' ):
default=data.get( 'default_value' )

result+="\\xdirective{dir}{"+directive+"}{"+datatype+"}{"+required+"}{"+default+"}{"+deprecated+"}{%\n"
result+="}\n\n"
result+="\\end{description}\n\n"
Expand Down

0 comments on commit 25a1f20

Please sign in to comment.