PDF version shows one huge chapter? Table of contents issues with latexpdf

[EMK]

I've been focusing on HTML for several months and now I'm trying to build PDF (via latexpdf) from the same files. 

I have one main toctree and several hidden toctrees. 

I'm having these problems:

 1) All my contents go in one chapter, everything from all the toctrees ends up as Chapter 1 for some reason. 

 2) Even though I have set maxdepth to 3 in the main toc, I only see one level of headers in the table of contents

 3) Documents in the hidden toctrees are listed in the table of contents. For example, I have a set of copyright statements and such in a hidden toctree to prevent warnings when I build, and it shows up in the PDF document table of contents

Note: We haven't updated from Sphinx 1.3 yet, so if that makes a difference we can upgrade. 

Here's an example of how my index.rst file looks: 

.. toctree::

   :maxdepth: 3

   :name: main

   

   intro

   common_tasks

   settings

   support

   

   :ref:`genindex`

   :ref:`search`

   

   appendix_1

   appendix_2

.. toctree::

   :hidden:

   :maxdepth: 1

   :name: common_tasks_toc

   

   task_1_overview

   task_2_overview 

.. toctree::

   :hidden:

   :maxdepth: 1

   :name: settings_toc

 

   settings_topic_1

   settings_topic_2

   settings_topic_3

.. toctree::

   :hidden:

   :name: hidden files

   

   frontmatter

   doc_warnings

   license_info

Here is what I am getting in my PDF table of contents: 

CONTENTS 

1. Contents 

 1.1    About MyProduct

 1.2    Common Tasks for MyProduct

 1.3    MyProduct Settings

 1.4    Contacting Support

 1.5    Appendix 1: Something Not Very Important

 1.6    Appendix 2: Something Else Of Limited Interest

 1.7    Task 1 Overview

 1.8    Task 2 Overview

 1.9    How To Set Item1

 1.10  How To Set Item2

 1.11  How To Set Item3

 1.12  Index and Search

 1.13  Copyright Information 

 1.14  Warnings Used in This Document

 1.15  License Information

What am I doing wrong here? 

[Jeff McKenna]

To learn settings for latex/pdf output, I suggest you follow other
project's implementations and look at their settings used - for example,
I champion sphinx/pdf output for the MapServer community, and it
automatically generates an 839 page PDF with proper toctrees/bookmarks.
Take a look at the Latex output section of my conf.py at
https://github.com/mapserver/docs/blob/branch-7-0/conf.py#L170 which
generates http://www.mapserver.org/pdf/MapServer.pdf

The preamble settings are very important.

-jeff

[Komiya Takeshi]

Hi,

 1) All my contents go in one chapter, everything from all the toctrees ends up as Chapter 1 for some reason. 

Please check your index.rst. Is there "Contents" heading before toctree definition?

If true, Sphinx recognized the heading is a top level chapter.

 

 2) Even though I have set maxdepth to 3 in the main toc, I only see one level of headers in the table of contents

Hmm... it's strange. But I updated the mechanism at 1.4 series.

So I want to upgrade your Sphinx to newest and try it again.

 

 3) Documents in the hidden toctrees are listed in the table of contents. For example, I have a set of copyright statements and such in a hidden toctree to prevent warnings when I build, and it shows up in the PDF document table of contents

"hidden" option does not mean "not listed in the ToC".

"hidden" option is described as following:

This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

http://www.sphinx-doc.org/en/stable/markup/toctree.html

It does not generate toctree links at the location only.

If you want to prevent warnings, please mark the document as :orphan:.

To use it, please refere following page:

http://www.sphinx-doc.org/en/stable/markup/misc.html?highlight=orphan#file-wide-metadata

Thanks,

Takeshi KOMIYA

2016年9月13日火曜日 6時57分46秒 UTC+9 EMK:

[EMK]

Thanks for the example, though I think my preamble settings are not at fault here. 

One of my motivations for using hidden toctrees was to define the sequence for "previous" and "next" links in the HTML documentation. Is there another way to specify that sequence? My motivation was to support sequential reading for files that I have pulled out into separate freestanding documents (rather than creating giant unwieldy HTML pages. That is, something like this: 

Overview of Owl Maintenance  

 

Be careful of their talons and beaks! Also, make sure the feathers are clean and shiny. 

  - Read more about talons (link to talon_maintenance.html)

  - Read more about beaks (link to beak_maintenance.html)

  - Read more about feathers (link to feather_maintenance.html)

For the previous/next links I want the overview to lead to talon_maintenance and that to beak_maintenance, etc. (This is not quite working exactly as I wanted now, but it's close enough.)

(Also, for Jeff - how do you get that local TOC in the sidebar for your HTML docs?)  

[EMK]

Ah! There was a Contents header. I removed it and now I am seeing chapters with a more appropriate number of subheads. 

I will look into the other things you mentioned. 

手伝ってくれてありがとう。Thank you for your help!

[EMK]

Can you give an example of how to use the orphan metadata tag? 

Things I don't understand and can't find from searching the documentation: 

• Where do I put the tag, in the file that is causing the build warning or in the TOC file?
• What syntax is used - is "orphan" meant to be the field name or field content term? 
• Is there another tag that goes with this syntax to hide it from the output? 

When I tried adding :orphan: at the top of my file, I didn't see the build warning, but the word "orphan:" also appeared on my HTML page.

[Komiya Takeshi]

Can you give an example of how to use the orphan metadata tag? 

Here:

:orphan:

Title of document
==================

blah blah blah...

 

• Where do I put the tag, in the file that is causing the build warning or in the TOC file?

The top of each files which are not listed in toctree.

 

• What syntax is used - is "orphan" meant to be the field name or field content term? 

"orphan" is a field name. orphan field does not need any content. so only `:orphan:` works well.

 

• Is there another tag that goes with this syntax to hide it from the output? 

When I tried adding :orphan: at the top of my file, I didn't see the build warning, but the word "orphan:" also appeared on my HTML page.

That's strange. The orphan metadata is not appeared in HTML docs.

Could you share your example?

Thanks,

Takeshi KOMIYA

[EMK]

Once again I should confess that I am running Sphinx v1.3.2, so if there have been bug fixes that address this, I need to upgrade. 

I am only using the :orphan: tag with files that are included in other files. It shows up in my HTML as orphan: and is formatted similar to a table header. 

[Komiya Takeshi]

 Ah, I understand your situation.

Sorry, :orphan: does not effect for this case.

The warnings from included files are resolved at 1.4.x series.

Please update Sphinx to newest one.

Thanks,

Takeshi KOMIYA

2016年10月13日木曜日 8時27分53秒 UTC+9 EMK:

[E. Kelly]

I moved the hidden toctrees to their introductory documents instead of the main index document, and it's working great. 

Example: 

index.rst: 

.. toctree::

   :maxdepth: 2

   :name: main

   

   intro

   common_tasks   

   settings_overview

common_tasks.rst: 

.. _common_tasks:

===============

Common Tasks 

===============

This article gives overview information about various configuration tasks.  

.. toctree::

   :hidden:

   :maxdepth: 1

   :name: common_tasks_toc

   

   task1_info

   task2_info

   task3_info

The "orphan" tag is still being processed as a table header or something in 1.4.8 - but I just won't use it, no big deal. 

Thanks.