# [sphinx-users] Re: how do I add subtitle?

Yes and no.

In the latex section of the conf.py, you will see a latex_elements dict
being defined.  This is where you can modify your preamble.  You can put
your definition there, but most people read in a separate file or two,
since when you update your document format, the changes can be extensive
and difficult to read in the conf.py.

My approach thus far was to create my own .sty to has commands to change
the headers/footers, and redefines \maketitle (which you can see part of in
the previous post).  The title is written on the page with this:
\begin{center}%
\sphinxlogo%

Which you can see in the sphinx.sty file.  This is probably where you would
want to put in a subtitle.  Note the Sphinx defines \@title, \py@release,
and \releaseinfo for you.  If you want any other variables, you will need
to define them in your preamble.  You get this added to your build
directory by modifying the latex_additional_files list in the conf.py:
]

I have followed other examples, by making the preamble its own .tex file
and treating that as string.Template object, so in my conf.py I have the
following:
PREAMBLE = string.Template(open(
os.path.join(os.path.abspath('.'),
'latex_templates/preamble.tex')

Then in the latex_elements dict in the conf.py I have:
latex_elements = {
...
'preamble': PREAMBLE.substitute(...),
...
}

Please look at some open source examples online for how other people have
their projects setup:

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

You can probably find more examples online.  These are two that I have read
through and found helpful.

On Thursday, October 13, 2016 at 1:09:00 PM UTC-7, Fiona Hanington wrote:
>
> Thank you for this!!   I do want a subtitle on the cover page of a PDF
> doc.   What file to I update with the content you've given?  (conf.py?)
>
> On Wednesday, 12 October 2016 17:33:08 UTC-7, Peter Burdine wrote:
>>
>> Can you clarify what you mean by "subtitle"?
>>
>> The reST you posted (assuming it is all in one file) says make a Heading
>> 1 ('Title'), followed by a Heading 2 ('subtitle') followed by a Heading 1
>> ('subsubtitle').  This is because you used the same character ('*') for
>> heading 1, then used it again for, for what looks like it should be, a
>> heading 3.  In reST, any 4 consecutive characters that begin a line can be
>> used as a heading indicator.  Overlines are optional, underlines are
>> manditory and need to be at least as long as the text they are trying to
>> over/underline.  If you use overlines, then they need to be the same length
>> as the underline.  If you follow the python guidelines, then use # for
>> heading 1, * for heading 2, and = for heading 3 (IIRC).
>>
>> It looks like you are trying to build a PDF from your question.  If
>> someone asked about a subtitle for PDF output, then I assume that they mean
>> some some text that is slightly smaller than the title, on the title page.
>> If this is what you want, you will need to modify your preamble to redefine
>> \maketitle.
>>
>> \renewcommand{\maketitle}{%
>>   \begin{titlepage}%
>>
>>   % Put your content here
>>
>>   \end{titlepage}%
>>   \cleardoublepage%
>>   \setcounter{footnote}{0}%
>>   \let\thanks\relax\let\maketitle\relax
>>   %\@ifundefined{fancyhf}{}{\pagestyle{normal}}%
>> }
>>
>> You can find the default definition in one of the .sty files that is
>> included with Sphinx.
>>
>> On Wednesday, October 12, 2016 at 4:27:53 PM UTC-7, Fiona Hanington wrote:
>>>
>>> Hi
>>>
>>> (Excuse the newby question -- I am new to rst and sphinx and the person
>>> who set things up here has left, so I am trying to work things out.)
>>>
>>> I need to add a subtitle to an existing doc.
>>>
>>> Sphinx docs on the internet tell me that to add a title/subtitle, I
>>> simply need to add this to my "file":
>>>
>>> *****
>>> Title
>>> *****
>>>
>>> subtitle
>>> ########
>>>
>>> subsubtitle
>>> ***********
>>> and so on
>>>
>>>
>>>
>>> However, I don't know where to add this.  If I look at my conf.py file,
>>> which currently has a project name that controls the doc title, it looks
>>> like this (title is not formatted as suggested above). Title is defined by
>>> what is in *project = *:
>>>
>>> from shared.conf import restrictions
>>> from shared.conf import *
>>> part = "09-1076A-D"
>>>
>>> # General information about the project.
>>> project = u'Getting Started'
>>>
>>> # The version info for the project you're documenting, acts as
>>> replacement for
>>> # |version| and |release|, also used in various other places throughout
>>> the
>>> # built documents.
>>> #
>>> # The short X.Y version.
>>> version = '2.6'
>>> # The full version, including alpha/beta/rc tags.
>>> release = version
>>>
>>> latex_preamble += r"""
>>> \def\part{%s}
>>> \newcommand{\argmin}{\operatornamewithlimits{argmin}}
>>> \newcommand{\argmax}{\operatornamewithlimits{argmax}}
>>> \newcommand{\vc}[1]{{\pmb{#1}}}
>>> \newcommand{\ip}[2]{\langle{#1},{#2}\rangle}
>>> \newcommand{\sign}{\operatorname{sign}}
>>> """ % dwave_part
>>>
>>> #latex_preamble += restrictions
>>>
>>> latex_documents = [
>>>     ('index', '%s_GettingStarted.tex' % (part), project,
>>>      name, 'manual'),
>>> ]
>>>
>>> pngmath_latex_preamble = latex_preamble
>>>
>>>
>>> Thank you!!
>>>
>>> Fiona
>>>
>>>

--
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