User:Svamberg/Making documentation

From FAIWiki
Jump to navigation Jump to search

This hook can create documentation from templates. It is fully configurable (preprocessing, postprocessing) and supports multiple documentation formats.

Install

  • get this source finish.DOC and store to $FAI/hooks
  • make directory $FAI/doc
  • add class DOC to your $FAI/class/ configuration

Name Convention

You can create some files or directories in the $FAI/doc directory. Files with the executable flag will be executed using the magical line (#!). Other files will be included into the documentation.

This script may be divided into 5 stages:

  1. opening documentation
    • files S[0-9][0-9].* - making document headers, preparing to make documentation
  2. the first part of the documentation
    • directories [0-9][0-9].* contain documentation or scripts sorted by name:
      • files S[0-9][0-9].* - first part of preprocessing, sorted by filename
      • files $class_name - second part, sorted by class priority
      • files K[0-9][0-9].* - third part, sorted by filename
  3. the second part of the documentation - ordered by class priority
    • $class_name files
    • $class_name directories - files in this directory ordered by filename
  4. closing documentation
    • files K[0-9][0-9].* - ordered by filename
  5. postprocessing
    • files P[0-9][0-9].* - add footer or document transformation

Configuration

All configuration varibles -- such as those determining the directory containing documentation sources, output files, comment types or active debuging -- are defined in the header of the hook script finish.DOC.

Example

This example is based on actual configuration for used to make documentation concerning the installation. Parts of the documentation are written in TeX. Output formats are tex, html and txt.

Documentation Sources

All source files are stored in the $FAI/doc directory.

Opening Documentation

File S00_tex_head with rihts of execution. 

#!/bin/sh
HOSTNAME=`hostname`

cat <<-EOF
\documentclass[12pt]{article}                     
\usepackage[czech]{babel}                                                       
\usepackage[latin2]{inputenc}                                     
\title{Installation documentation for server \tt{$HOSTNAME}}
                                                          
\begin{document}  
EOF

The First Part of the Documentation

Creates the first section about changes that need to be made after the installation such as setting new passwords, making updates, firewall updates, etc.

File S00_postinst/S00_section is readable: 

\section{Changes after installation}
List of all changes in this section you need to make after installation.

File S00_postinst/SRV is readable, this filename is named by class SRV 

\subsection{{\tt SRV}}
\begin{itemize}
        \item change password
        \item make security updates:
        \begin{verbatim}
apt-get update
apt-get upgrade
        \end{verbatim}
\end{itemize}

The Second Part of the Documentation

File DEFAULT/00 is not executable and is used to store the section header. 

\section{General configuration -- {\tt DEFAULT}}

File DEFAULT/30_dpkg is executable and generates the list of all installed packages 

#!/bin/sh

dpkg_list=`dpkg --root=$target -l`

cat <<-EOF
\subsection{List of installed packages}
\begin{verbatim}
$dpkg_list
\end{verbatim}

EOF

Closing Documentation

File K90_tex_foot is not executable: 

\end{document}

Postprocessing

Create new html and txt files from the output document /tmp/fai/doc.tex . File P10_export is executable: 

#!/bin/sh

# make HTML version
tth < /tmp/fai/doc.tex > /tmp/fai/doc.html

# make TXT version
links -dump -assume-codepage iso-8859-2 /tmp/fai/doc.html > /tmp/fai/doc.txt

File P90_copy is executable and copies the resulting documentation into the target filesystem: 

#!/bin/sh

cp /tmp/fai/doc.* $target/root/

Output

This example has three output files. All output files are shortened. The main documentation file is doc.tex 

% ### BEGIN: /fai/doc/S00_tex_head (exec) ###
\documentclass[12pt]{article}
\usepackage[czech]{babel}
\usepackage[latin2]{inputenc}
\title{Installation documentation for server \tt{fai-server}}

\begin{document}
% ### END:   /fai/doc/S00_tex_head (exec) ### 
% ### BEGIN: /fai/doc/00_postinst/S00_section (read) ###
\section{Changes after installation}
List of all changes in this section you need to make after installation.
% ### END:   /fai/doc/00_postinst/S00_section (read) ### 
% ### BEGIN: /fai/doc/00_postinst/SRV (read) ###
\subsection{{\tt SRV}}
\begin{itemize}
        \item change password
        \item make security updates:
        \begin{verbatim}
apt-get update
apt-get upgrade
        \end{verbatim}
\end{itemize}
% ### END:   /fai/doc/00_postinst/SRV (read) ### 
% ### BEGIN: /fai/doc/DEFAULT/00 (read) ### 
\section{General configuration -- {\tt DEFAULT}}
% ### END:   /fai/doc/DEFAULT/00 (read) ### 
% ### BEGIN: /fai/doc/DEFAULT/30_dpkg (exec) ###
\subsection{List of installed packages}
\begin{verbatim}
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Installed/Config-files/Unpacked/Failed-config/Half-installed
|/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
||/ Name           Version        Description
+++-==============-==============-============================================
ii  adduser        3.63           Add and remove users and groups
ii  apt            0.5.28.6       Advanced front-end for dpkg
ii  apt-utils      0.5.28.6       APT utility programs
...
ii  xfsprogs       2.6.20-1       Utilities for managing the XFS filesystem
ii  xlibs-data     4.3.0.dfsg.1-1 X Window System client data
ii  zlib1g         1.2.2-4        compression library - runtime
\end{verbatim}

% ### END:   /fai/doc/DEFAULT/30_dpkg (exec) ### 
% ### BEGIN: /fai/doc/K90_tex_foot (read) ### 
\end{document}

% ### END:   /fai/doc/K90_tex_foot (read) ###

HTML version is stored in the doc.html file, html code formating is ugly. Showing it is not necessary.

TXT version is in the doc.txt file 

                Installation documentation for server fai-server

1  Changes after installation

   List of all changes in this section you need to make after installation.

  1.1  SRV

     * change password
     * make security updates:

 apt-get update
 apt-get upgrade


2  General configuration - DEFAULT

  2.1  List of installed packages

 Desired=Unknown/Install/Remove/Purge/Hold
 | Status=Not/Installed/Config-files/Unpacked/Failed-config/Half-installed
 |/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
 ||/ Name           Version        Description
 +++-==============-==============-============================================
 ii  adduser        3.63           Add and remove users and groups
 ii  apt            0.5.28.6       Advanced front-end for dpkg
 ii  apt-utils      0.5.28.6       APT utility programs
 ...
 ii  xfsprogs       2.6.20-1       Utilities for managing the XFS filesystem
 ii  xlibs-data     4.3.0.dfsg.1-1 X Window System client data
 ii  zlib1g         1.2.2-4        compression library - runtime


     ----------------------------------------------------------------------

   File translated from TEX by TTH, version 3.67.
   On 4 Dec 2005, 13:31.
Retrieved from "https://wiki.fai-project.org/index.php?title=User:Svamberg/Making_documentation&oldid=3199"