how do I add revision history table?

[Fiona Hanington]

Hi there

I would like to include a revision history table as part of the front matter of my documents (PDF). I'd like this to appear after the title page and before the toc if possible. Does sphinx/rst support this? If so how would I go about it?

Thanks

Fiona

[Peter Burdine]

In the latex output, all of the front matter ouput (title page, toc, etc) is controlled by the \maketitle command.  If you want to change the front matter you need to renew that command to change its behavior.

[EMK]

I'm having a similar problem and haven't been able to figure it out on my own. I want to put copyright information between the table of contents and the first chapter. 

I realize that I have to override \maketitle but I haven't been able to find the original source for it to modify, or documentation about how to do it within Sphinx.  

I found parts of \maketitle in lib/python2.7/site-packages/sphinx/texinputs/sphinxmanual.cls but wasn't able to understand how to add extra pages. (I am not familiar with LaTeX, which doesn't help.) It also must be pulling elements from another source, since I don't see a format code that makes everything on the title page bold, but it is (I would like to have some things not boldface).

Fiona, have you found a solution? 

[Komiya Takeshi]

Hi,

You can override the LaTeX macros in your conf.py:

latx_elements = {
    'preamble': """
\renewcommand{\maketitle}{%
...
}
"""
}

Anyway, you have to learn about LaTeX macros to customize LaTeX output.

Thanks,

Takeshi KOMIYA

2016年10月20日木曜日 8時03分01秒 UTC+9 E. Kelly:

[Peter Burdine]

The maketitle command can be found in the sphinxmanual.cls file.  This can be used as a starting point.  Once you start modifying your latex format, it will a lot of room in your conf.py file.  Eg the default \maketitle is 42 lines long.  It seems most people create a file with the contents of their preamble, then load the file a string (or string.Template) in their conf.py file to make it cleaner.

I'm looking back at my configuration now and remember why this was so confusing to implement.  The front matter is actually controlled by the 'tableofcontents' value in the latex_elements dict (which defaults to \maketitle):

latex_elements = {
    ...  
    'tableofcontents': '\maketitle',
    ...
}

As a side note, should that entry be changed to 'frontmatter' or something less misleading than 'tableofcontents'?

I set 'tableofcontents' to be:

r'''
    \setupHeadFootForFrontMatter   % Define header/footer for front matter
    \formattoc                     % Change the style of the table of conents
    \maketitle                     % Create the title page
    \signaturepage                 % Create the signature page
    \revisionhistory               % Add the revision history page
    \tableofcontents               % Add the table of content
    \clearpage
    \listoffigures                 % Add table of figures
    \clearpage
    \listoftables                  % Add table of tables
    \clearpage
    \setupHeadFootForText          % Setup formatting for the rest of the document
    \pagenumbering{arabic}
    \pagestyle{plain}
'''

All of the above commands are stored in the preamble file, which I read in as a string.Template.  For the revision history, I actually have that as a .yml file with the entries that I need there, then I have some python code to translate the YAML into a rows/columns in LaTeX.  This gets substituted in the sting template.  It looks something like:

\newcommand{\revisionhistory}{
  \renewcommand\cellalign{tl}
    \begin{center}
        \huge \textbf{Change Record} \normalsize
        \vspace{3em}
        \renewcommand{\arraystretch}{1.4}
        \begin{longtable}[c]{ | c | p{4in} | p{1in} |c | }
        \hline
            \multicolumn{1}{|c|}{\underline{REV}} &
            \multicolumn{1}{c|}{\underline{TECHNICAL REASON}} &
            \multicolumn{1}{c|}{\makecell[bc]{SECTIONS \\
                                          \underline{AFFECTED}}} &
            \multicolumn{1}{c|}{\makecell[bc]{RELEASE \\
                                          \underline{DATE}}} \\
        \endfirsthead

        \multicolumn{4}{c}%
        {{\bfseries \tablename\ \thetable{} -- continued from previous page}} \\
        \hline
            \multicolumn{1}{|c|}{\underline{REV}} &
            \multicolumn{1}{c|}{\underline{TECHINICAL REASON}} &
            \multicolumn{1}{c|}{\makecell[bc]{SECTIONS \\
                                          \underline{AFFECTED}}} &
            \multicolumn{1}{c|}{\makecell[bc]{RELEASE \\
                                          \underline{DATE}}} \\
        \endhead

        \hline \multicolumn{4}{|r|}{{Continued on next page}} \\
        \endfoot

        \hline
        \endlastfoot
       
        ${revisionhistory}   % The output of the yaml to latex goes here
       
        \end{longtable}
    \end{center}
    \newpage
}

To get the same content in HTML format, I use the jinja extension.  This loads the same revision history .yml file as a context, then creates a reST table inside a ".. only::html" block.

As a side note, doing front matter in Sphinx is hard.  It seems like there would be a way to do it using the latex_documents value in the conf.py, but that doesn't tie in well with HTML or any other output format.  So you end up having to resort to using a series of workarounds like the one listed above.

The good news is that if you are making a lot of documents, you can share the preamble file (since the code executed in the conf.py file can see outside your doc directory), you can even have your conf.py file 'exec' other python files, so you can put most of your document defaults in a common file, then have only the specific information for your current document in the conf.py.  This makes it so you can have a "template" document that is easy so start so you don't have to do a lot of the boiler plate tasks as often.

If you want PDF output from sphinx, I don't think there is any way around learning at least basic Latex.  It is not easy.