I think the root cause of this issue is the way the builders approach the documents. HTML is a straight forward 1:1 translation, the latex builder kind of does the same thing. The issue is that it is LaTeX that builds the table of contents and other front matter for the document (with the \tableofcontents command), then the contents are appended to the .tex file. This is why the contents appears to be moved. In the HTML builder, sphinx does all of the numbering and generating of the table of contents, but for latex, the builder writes out \part, \section, \subsection, etc and then latex builds the toc from there. The latex toc only sees the definition of sections (titles only) not the rest of the content. The content gets added only after the front matter. If you watch the build output, you will see this as it lists each .rst file as it gets appended to the .tex file. Hopefully this makes sense. I've been playing with Sphinx for 3 months and it is only now making sense to me.
See this thread "how do I add revision history table? <https://groups.google.com/forum/#%21topic/sphinx-users/DVAQTKpSens>". While there are other threads the discuss front matter, this is the most recent. AFAIK there is no obvious or easy way to do this. https://groups.google.com/forum/#!topic/sphinx-users/DVAQTKpSens The above thread will point you to writing all of that in Latex, that is not easy and doesn't translate to multiple output types. After thinking about this for a bit, here is guess as to an approach that might work: There should be a way to do it using the latex_documents field in the conf.py file. There of course will be some confusion on how that works because you will then need to move your forward to another .rst file then use an .. include inside of an .. only:: html block to get it working for html, then do something differently for latex. Then you will also need to redefine the latex commands to create the front matter. Then you would then have to put some .. only:: latex blocks after the forward to reinsert the table of contents and other front matter in the correct locations before the document main content. Now I am thinking about how I would want to do it, the HTML and Latex builder put things together so differently that this does not sound like an easy task. If we can come up with a general approach I think that would help a lot of people. I haven't played with anything other than html/latex, so I don't have any idea how the others work (though a forward and other front matter don't make really make sense for man/info pages). --Peter On Thursday, October 27, 2016 at 2:17:35 PM UTC-7, Warren Block wrote: > > We would like to include a foreword before the table of contents page > for a short introduction. Coming before the TOC, this presumably would > not be listed in the TOC. > > Including text in the index file before the toctree directive seemed > like a way to do this: > > Document Sample > =============== > > Foreword > -------- > > Welcome to this document! > > .. toctree:: > :numbered: > :maxdepth: 4 > > intro > ... > > > When rendered to PDF, the Foreword title appears as the first title of > the TOC, and the "Welcome to this document!" text appears as the first > text in the intro chapter. > > Some searching found people asking how to accomplish this, but no clear > answers. Can it be done? > > The fall-back plan is to create a one-page PDF foreword and use a PDF > merge utility like pdftk to combine that with the PDF created by sphinx. > That's not elegant and introduces more dependencies. Is there a better > way? > -- 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+unsubscr...@googlegroups.com. To post to this group, send email to sphinx-users@googlegroups.com. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
