5

I'm generating Django documentation to more easily reference it in Emacs. The obvious approach[^] results in cross-references having "see" prepended to them. E.g., the online documentation for Model instances says:

This document describes the details of the Model API. It builds on the material presented in the model and database query guides, so you’ll probably want to read and understand those documents before reading this one.

whereas opening the texinfo in Info results in:

This document describes the details of the ‘Model’ API. It builds on the material presented in the see model and see database query. guides, so you’ll probably want to read and understand those documents before reading this one.

How can I get rid of this "see"?

[^]: The obvious approach being: 

git clone https://github.com/django/django.git
cd django && git checkout stable/1.11.x
cd docs && make texinfo
cd _build/texinfo && sudo make install-info
Felipe
  • 329
  • 1
  • 8

1 Answers1

4

I was looking for the variable Info-hide-note-references. Specifically, setting it to 'hide results in the behavior I want. The Sphinx FAQ goes into more detail about this, and suggests the following advice to automatically enable this on sphinx-generated files (Fixed since the regex they suggest wasn't working)

(defvar-local Info-hide-note-references t)

(defun fov-auto-hide-info-note-references (&rest _args)
  "Advice to automatically hide 'see' in info files generated by sphinx."
  ;; Adapted from http://www.sphinx-doc.org/en/stable/faq.html#displaying-links
  (save-excursion
    (save-restriction
      (widen)
      (goto-char (point-min))
      (when (re-search-forward
             "^ *Generated by \\(Sphinx\\|Docutils\\)"
             (save-excursion (search-forward "\x1f" nil t)) t)
        (setq Info-hide-note-references 'hide)))))

(advice-add 'info-insert-file-contents :after #'fov-auto-hide-info-note-references)
Felipe
  • 329
  • 1
  • 8
  • I wonder if Sphinx could be convinced to write a file-local variable to set this up automatically? – npostavs Mar 15 '18 at 00:05
  • That's a phenomenal idea! You could probably do it as part of the build step in shell even if Sphinx doesn't comply – Felipe Mar 15 '18 at 00:15