What follows is a lengthy explanation and then two questions: by way of
summary, I've run across what I think might be a bug, or perhaps a request
for enhancement, and I'd like to request a change in Sphinx's behaviour...
Background
---
I have been using my own theme, based on Haiku, that uses the template
variables {{ next.title }} and {{ prev.title }} in order to show the title
of a topic's related pages, building links to those pages.
Also, I have been using the .. title:: directive in my topics in order to
have a title that I can render in the "title bar" of my HTML output pages
and not have a title like this:
====
Title
====
Show up on the page right under the title bar. Instead, I do this:
.. title:: Title
Introductory paragraph of topic page.
First section title
--------------------
It looks nicer in our rendered HTML docs.
Until very recently, I could have sworn that when I used a construction
like that, the templating variables passed down to jinja gave "prev.title"
and "next.title" as the text found in the .. title:: directive (i.e. in
this case, prev.title if my example were the previous topic would resolve
to "TItle", and not "First section title").
However, within the past week or so that's now changed -- now (with Sphinx
1.1.2 and docutils 0.8.1), with my example, prev.title resolves to "First
section title" and not "Title".
After digging into the source, I found that if I made a subtle change to
the html.py builder file's definition of
StandaloneHTMLBuilder.get_doc_context(self,docname,body,metatags), I could
fix this. Previously, the first variable assignments in that method did
this:
prev = next = None
parents = []
rellinks = self.globalcontext['rellinks'][:]
related = self.relations.get(docname)
titles = self.env.titles
I changed the definition of titles to this:
titles = self.env.longtitles
Checking env, I noticed that longtitles[] was meant to be "the same as
titles[], unless you use the ..titles:: directive to override it".
Request
---
I don't necessarily mean to suggest I've uncovered a bug, but I think it'd
be useful to let the use of .. title:: get through to the templating level
in the way I'm using it, especially at some point in the past month or so,
it did seem to be doing this (I have sadly been unable to reproduce a
precise version of Sphinx+docutils that does, in fact, confirm my memory
that it worked this way at one point).
I can see two ways to address this issue -- the quick and dirty way seems
to be to set the "title" properties for the related nodes (like next and
prev) that the template can refer to, to a value taken from the longtitles
list rather than the titles list. This way .. titles:: will always override
a title set in the document's body itself.
However, I can also see that the /right/ way to fix this might be to expose
a "prev.title" property /and/ a "prev.metatitle" property to the templating
level so that both bits of information might be available. I'm not at all
comfortable enough with the codebase to suggest how that might be done,
though.
Indeed, I have no confidence that my change to the source is even the right
way to implement the "quick fix": it works for my narrow use case, as far
as I can tell, but it might break other things, or not be best implemented
there.
Does anyone have any thoughts on this matter? Can anyone make suggestions
on how it /might/ be best to implement this change, to expose the contents
of .. title:: up to the templating level through the 'next' and 'prev'
related nodes?
Thanks,
--
Viktor Haag
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To view this discussion on the web visit
https://groups.google.com/d/msg/sphinx-dev/-/VK3x03XGkMUJ.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
