How to restore target number references?

[KubaO]

0.5.2 broke references that were meant to be names (e.g. command names) and replaced them with Section n.n.n. How to restore old behavior? The changelog is very vague:

docutils/Sphinx frontend: will default to referencing targets by number if possible, even if a custom label is explicitly set. This behaviour can be overridden in the style sheet by setting the type style property to ‘custom’.

This is very vague. What would be a complete example of reverting this to all behavior, for all headings?

The below doesn't work and produces the following warning: Unsupported options passed to stylesheet: type

[STYLESHEET]
name = Specification
base = sphinx
type = custom

[brechtm]

Hi @KubaO,

Yes, the provided information in the changelog is not quite sufficient to figure things out. The manual, while it could benefit from more work, should provide much more insight into how things work; see the Basic Styling and Element Styling sections.

You can figure out which style you need to adjust by means of the style log. Search the log for the text/object you want style differently. In this case, this should point you to the linked reference style. The following style sheet should do it:

[STYLESHEET]
name = My custom style sheet
base = sphinx

[linked reference]
type = custom

This will reset the behavior to what it was prior to 0.5.2. You can still use the :numref: role to explicitly reference elements by number (which does require setting numfig = True, also affecting HTML output).

[KubaO]

That did the trick. Thank you! The style log is a useful thing to know about as well.

[marcus67]

Hi @brechtm, thank you this wonderful piece of software! The behavior described in this issue was the aspect that prevented me from using rinohtype for my documentation. The problem is that Google searches do not help at all. Then I tried to scan the issues for any hints. With the filter active for open issues only this did not yield any result. Only when I came back to the issues and searched the closed issues I was successful. In think you should definitely include this hint in a place where Google can find it with a title such as "Showing section headers instead of section numbers when generating PDF files using Sphinx and rinohtype". Thanks a lot! Marcus

[brechtm]

@marcus67 Thanks for letting me know. Documentation is unfortunately quite lacking at this moment due to the limited time I can spend on rinohtype. I'll reopen this ticket as a reminder to add a FAQ entry about this.

[brechtm]

From my answer to Rinohtype link text is “Section 3.1” instead of the text specified in the link or link target on StackOverflow, changes to docutils/Sphinx could improve this situation:

• [ ] reference nodes could indicate whether the user supplied a custom title for the link
• [ ] Sphinx could allow defining new roles based on :ref: