how do I add subtitle?

[Fiona Hanington]

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

#add restrictions

#latex_preamble += restrictions

latex_documents = [

    ('index', '%s_GettingStarted.tex' % (part), project,

     name, 'manual'),

]

pngmath_latex_preamble = latex_preamble

Thank you!!

Fiona

[Peter Burdine]

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.

[Fiona Hanington]

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

[Peter Burdine]

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%
      {\rm\Huge\py@HeaderFamily \@title \par}%
      {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}

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:

latex_additional_files = ['your_sty_file.sty',
                         ]

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')
                ).read())

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.

[Fiona Hanington]

thank you so much for the reply.   I'll look at these things and see how I do. Appreciate the links to the examples.