Actual, working example of latex-pdf cover page?

[Warren Block]

Is there an actual, complete example that shows the magical mix of files
and latex commands to produce a modified cover sheet? A trivial example
would be fine.

It appears that \maketitle needs to be redefined, but my attempts at
that fail with TeX errors. Or I could define my own and set 'maketitle'
in latex_elements in conf.py. Maybe. So far, none of the examples I
have found show an actual, complete, working example.

Given that this is the only way to create a custom cover page with the
default Sphinx configuration, such an example should be part of the
Sphinx docs.

I am using Sphinx 1.4.8.

[Peter Burdine]

I can't share my exact coverpage, but here are some references I used when learning how to do it:

• https://github.com/mapserver/docs
• https://github.com/i6/ibg

I generate a variety of documents, but they all have the "same" title page format, but the title, document number, etc differ.  I store my preamble in a file that is a string.Template and then load it.

PREAMBLE = string.Template(open(
                os.path.join(os.path.abspath('.'),'latex_templates/preamble.tex')
                ).read())

Then I define the following for the front matter (note that some of these are commands defined in the preamble or other included .tex/.sty file):

latex_contents = r'''
    \setupHeadFootForFrontMatter
    \formattoc
    \maketitle
    \signaturepage
    \revisionhistory
    \tableofcontents
    \clearpage
    \listoffigures
    \clearpage
    \listoftables
    \clearpage
    \setupHeadFootForText
    \pagenumbering{arabic}
    \pagestyle{plain}
'''

Now apply them in latex_elements:

latex_elements = {
    # ... put your stuff here
    # Customize below for your template
    'preamble': PREAMBLE.substitute(docrevision=document_rev,
                                    documentnumber=documentnumber,
                                   ),
    # Redefine tableofcontents to be the commands you want to run
    'tableofcontents': latex_contents,                                

    # Make this not look like a book
    'classoptions': ',openany,oneside',

    # .. Anything else you want to do
}

If you have additional latex files that are required (eg your own style file) add them below that:

latex_additional_files = ['latex_templates/my_style.sty',
                         ]

Now here is what my title pages looks like:

\renewcommand{\maketitle}{%
  \begin{titlepage}%
    \pagenumbering{roman}
    \thispagestyle{titlepage}
    \let\footnotesize\small
    \let\footnoterule\relax
    %\rule{\textwidth}{1pt}%
    \ifsphinxpdfoutput
      \begingroup
      % These \defs are required to deal with multi-line authors; it
      % changes \\ to ', ' (comma-space), making it pass muster for
      % generating document info in the PDF file.
      \def\\{, }
      \def\and{and }
      \pdfinfo{
        /Author (\@author)
        /Title (\@title)
      }
      \endgroup
    \fi
    \begin{center}%
      {\rm\Huge\py@HeaderFamily \@title \par}%
      {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
      \vfill
      {\LARGE\py@HeaderFamily
        \begin{tabular}[t]{c}
          \@author
        \end{tabular}
        \par}
        \py@authoraddress \par
      \vfill\vfill
      {\large
       \vfill
       %\@date \par
       \vfill
      }%
    \end{center}%\par
    \@thanks
  \end{titlepage}%
  \cleardoublepage%
  \setcounter{footnote}{0}%
  \let\thanks\relax\let\maketitle\relax
  %\@ifundefined{fancyhf}{}{\pagestyle{normal}}%
}

The preamble has sections that look like this to make it work like a template:

\def\documentnumber{${documentnumber}}
\def\docrevision{${docrevision}}

It really is only a slightly modified version, but I broke out the table of contents into latex_contents. Then added table of tables, table of figures, modified the headers/footer, etc there as well.


If you look around, you can find other open sourced projects that are good examples.

Latex is its own language and with most languages, there are about 15 ways of doing thing.  I spent a lot of time googling how things work before I was able to get something working that looked nice.

[Warren Block]

At this point, I have discovered that redefining \maketitle results in
the parameters/variables not be expanded. From conf.py:

'preamble': r'''
\renewcommand{\maketitle}{
\begin{titlepage}
\noindent \Huge \@date \par
\end{titlepage}
}'''

produces a title page with the word "date" rather than the date. The
values are defined in the .tex file, but not expanded. Defining a new
title routine and setting it as 'maketitle' has the same behavior.

[Warren Block]

On Thu, 15 Dec 2016, Peter Burdine wrote:

> I can't share my exact coverpage, but here are some references I used when learning how to do it:

> * https://github.com/mapserver/docs
> * https://github.com/i6/ibg

>
> I generate a variety of documents, but they all have the "same" title page format, but the title, document number, etc differ.  I store my preamble in a file that is a
> string.Template and then load it.
>
> PREAMBLE = string.Template(open(
>                 os.path.join(os.path.abspath('.'),'latex_templates/preamble.tex')
>                 ).read())

I have been just including the text of the preamble in conf.py for
simplicity. I did verify that it was written unchanged to the generated
.tex file.

> Then I define the following for the front matter (note that some of these are commands defined in the preamble or other included .tex/.sty file):
>
> latex_contents = r'''
>     \setupHeadFootForFrontMatter

This is far beyond what I am trying to do. I literally just need to put
the title of the page on the left instead of the right. Elite level
would be changing fonts and maybe drawing a blue box. Seriously.

> Now apply them in latex_elements:
>
> latex_elements = {
>     # ... put your stuff here
>     # Customize below for your template
>     'preamble': PREAMBLE.substitute(docrevision=document_rev,
>                                     documentnumber=documentnumber,

Hmm. These are extra parameters? The normal expected parameters
(title, date, author) were already defined in the .tex file:

\title{Title of Book}
\date{Dec 15, 2016}
\release{.1}
...

I have seen that section of code enough today to memorize it and
recognize your changes. Yours gives me a new '<argument>
\undefinedpagestyle' error, but that is trivial. Commenting that gives
the error I have seen with monotonous regularity:

! Missing number, treated as zero.
<to be read again>

> The preamble has sections that look like this to make it work like a template:
>
> \def\documentnumber{${documentnumber}}
> \def\docrevision{${docrevision}}
>
>
>
> It really is only a slightly modified version, but I broke out the table of contents into latex_contents. Then added table of tables, table of figures, modified the
> headers/footer, etc there as well.
>
>
> If you look around, you can find other open sourced projects that are good examples.

Oh, I found them. :) What I have not yet found is one that actually
works at all in this Sphinx environment. If the TeX code compiles, it
does not substitute variable values. More often, it gives the missing
number error, which appears to be the tex general error.

> Latex is its own language and with most languages, there are about 15 ways of doing thing.  I spent a lot of time googling how things work before I was able to get
> something working that looked nice.

Well, there is doing something with stock LaTeX, and there is doing
something within the Sphinx environment with it. The contrast between the
simplified markup of Sphinx and being thrown into full-blown TeX (well,
LaTeX) just to modify a title page is... interesting. This seems like
it should be a trivial thing, or if non-trivial, at least have been
needed so often that there would be an example of it in the manual. If I
can develop that, I will contribute it.

In any case, I appreciate your help. I will keep banging my head on
this.

> On Thursday, December 15, 2016 at 8:04:46 AM UTC-8, Warren Block wrote:
> Is there an actual, complete example that shows the magical mix of files
> and latex commands to produce a modified cover sheet?  A trivial example
> would be fine.
>
> It appears that \maketitle needs to be redefined, but my attempts at
> that fail with TeX errors. Or I could define my own and set 'maketitle'
> in latex_elements in conf.py.  Maybe.  So far, none of the examples I
> have found show an actual, complete, working example.
>
> Given that this is the only way to create a custom cover page with the
> default Sphinx configuration, such an example should be part of the
> Sphinx docs.
>
> I am using Sphinx 1.4.8.
>

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.
>
>

[Komiya Takeshi]

Hi,

At preamble part, The "@" sign is not expanded.

Please use \makeatletter before that like following:

    'preamble': r'''

       \makeatletter

       \renewcommand{\maketitle}{

         \begin{titlepage}

         \noindent \Huge \@date \par

         \end{titlepage}

       }

       \makeatother''',

Thanks,

Takeshi KOMIYA

2016年12月16日金曜日 8時41分56秒 UTC+9 Warren Block:

[Warren Block]

On Thu, 15 Dec 2016, Komiya Takeshi wrote:

> Hi,
> At preamble part, The "@" sign is not expanded.
> Please use \makeatletter before that like following:
>     'preamble': r'''
>        \makeatletter
>        \renewcommand{\maketitle}{
>          \begin{titlepage}
>          \noindent \Huge \@date \par
>          \end{titlepage}
>        }
>        \makeatother''',

Aha! I had tried using \makeatletter, but inside the \renewcommand. It
works this way! Thank you!

[Warren Block]

On Thu, 15 Dec 2016, Peter Burdine wrote:

> I can't share my exact coverpage, but here are some references I used when learning how to do it:

> * https://github.com/mapserver/docs
> * https://github.com/i6/ibg

Sorry, somehow I didn't even see these the first time. That second one
has a good example. Would be a good thing if the Sphinx docs linked to
it.

Thanks!

[Warren Block]

On Thu, 15 Dec 2016, Peter Burdine wrote:

> Then I define the following for the front matter (note that some of these are commands defined in the preamble or other included .tex/.sty file):
>
> latex_contents = r'''
>     \setupHeadFootForFrontMatter
>     \formattoc
>     \maketitle
>     \signaturepage
>     \revisionhistory
>     \tableofcontents
>     \clearpage
>     \listoffigures
>     \clearpage
>     \listoftables
>     \clearpage
>     \setupHeadFootForText
>     \pagenumbering{arabic}
>     \pagestyle{plain}
> '''

Can this be used to control the order of Sphinx-generated elements, like
to put a copyright page before the table of contents? (That can be done
by editing the generated .tex file, moving the call to \tableofcontents,
but that's ugly.)

[Peter Burdine]

Yes, that is exactly why it is setup that way.  Remember that it is only part of the solution.  The latex code still needs to in the preamble or a style file and you need to overwrite the correct entry in the latex_elements dict.

This is only for latex output so none of this information is in .rst files.   I am not sure what you meant by "Can this be used to control the order of Sphinx-generated elements".

--
You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/S_ip2b-lrRs/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sphinx-users+unsubscribe@googlegroups.com.

[Warren Block]

On Mon, 19 Dec 2016, Peter Burdine wrote:

> Yes, that is exactly why it is setup that way.  Remember that it is only part of the solution.  The latex code still needs to in the preamble or a style file and you need to overwrite the correct entry in the latex_elements dict.
>
> This is only for latex output so none of this information is in .rst files.   I am not sure what you meant by "Can this be used to control the order of Sphinx-generated elements".

The hope was that it would allow putting a section of copyright and
trademark information before the table of contents, yet still being able
to write that section in rst for consistency with the rest of the
document and being able to generate both HTML and PDF output from it.

But no, it appears not.

[Peter Burdine]

There should be a slightly less obvious way to do it.  I have considered doing it, but it makes the .rst files a bit more difficult to read.  Note that I have not tried this, it is only a guess at what you would need to do.

First redefine the latex_elements dict:

latex_elements = {
    # ... put your stuff here
    # Customize below for your template

    'preamble': my_preamble,

    # Redefine tableofcontents to be the commands you want to run

    'tableofcontents': \make_title_page_only,                                

    # .. Anything else you want to do
}

Then in your preamble, define \make_title_page_only to print just the title page.  Eg remove \tableofcontents

Now, update your index.rst file to have a toctree that isn't numbered:

.. toctree::
   
    copyright
    trademark
    main_toctree

Now you can put in your copyright, etc

Move the normal toctree into a separate file called main_toctree.rst (or pick a better name).  In that one, you probably want it numbered:

.. raw:: latex

    \tableofcontents

.. toctree::
    :numbered:
    :glob:

    put_your_previous_toctree_entries_here    

Now your .rst files should build your html files and latex files in the same order and you *should* be able to have .rst content before your table of contents.  This now makes it a bit more difficult to get your header/footers correct (if you switch between roman/arabic numbers in you footers for example).  You maybe able work around this by including more .. raw:: latex directives.

If you go that route and it works, please let me know.

[Fiona Hanington]

If you need this info in HTML too, duplicate the content (or single-source/reuse it using the include directive), and then use the only directive so it appears only in the HTML:

.. only:: html

--

You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscribe@googlegroups.com.

[Warren Block]

I did manage to accomplish this with exactly this type of ugly hackery
to the generated .tex file, and will post that in a new thread for easy
responses.