1

From the Sphinx Documentation environment, I am creating a pdf document using pdflatex.

To navigate between source files, in some of the files I have added links using label and ref which work abosolutely fine in the HTML documentation. However, the said links do not show up in the generated pdf file.

I am reproducing (part of) my .rst files with reference between them:

File define_ques_list.rst (From this file I call the file capa.rst)

###################
Question List
###################

**Definition**

Question lists are multilingual collections of questions that are answered during the exe...

:ref:`CAPA <corr-n-prev-action-capa-label>`

.. index:: question list

File capa.rst

.. _corr-n-prev-action-capa-label:

##########################
CAPA
#########################


Corrective Actions/Preventive Actions
-------------------------------------

**Definition**

*Corrective Actions*

These are actions that are deemed necessary to eliminate the cause of errors that were determined dur...

*Preventive Actions*

These are actions that are deemed necessary to eliminate the causes of possible errors before they ...

.. index:: corrective action CAPA

I checked the (relevant) contents in file *.tex and can see the following:

\chapter{Question List}
\label{\detokenize{modules/definitions/define_ques_list:question-list}}\label{\detokenize{modules/definitions/define_ques_list:question-list-href-label}}\label{\detokenize{modules/definitions/define_ques_list::doc}}
\sphinxstylestrong{Definition}

Question lists are multilingual collections of questions that are answered during the exe...

\DUrole{xref,std,std-ref}{CAPA}    <= This is the hyperlink as translated?

\index{question list@\spxentry{question list}}\ignorespaces

My question is: Why are my hyperlinks missing from the pdf file?

mzjn
  • 48,958
  • 13
  • 128
  • 248
shaan
  • 351
  • 2
  • 15
  • Actually I have run `make latexpdf` a number of times, but there has been no change (**links not appearing**). There are no errors or warnings during the `make latexpdf` run. The files that are not there in the `toctree` show up during html doc creation (`make html`) as WARNING. But those I believe will not cause problem to actual navigation (as I am able to navigate between files in HTML doc). A [ref](https://stackoverflow.com/questions/15249340/warning-document-isnt-included-in-any-toctree-for-included-file). – shaan Aug 13 '20 at 14:40
  • "The files that are not there in the toctree...". I think this might be the problem. If the file with the cross-reference target is not in the toctree, the cross-reference does not work. I can reproduce that. – mzjn Aug 13 '20 at 15:02
  • But at least the _hyperlink_ must show up in the pdf, isn't it? **Or may be I am wrong.** I am trying to include one of the files in a file which is already part of the **toctree**. I will get back in a minute. – shaan Aug 13 '20 at 15:09
  • No, unable to add a reference to the **called** file like done [here](https://stackoverflow.com/q/15249340/13823230). Coming up with: `WARNING: duplicate label corr-n-prev-action-capa-label, other instance in /.../docs/modules/definitions/capa.rst`. What is the system pointing me to? What is **duplicate**? – shaan Aug 13 '20 at 15:24
  • Looking into my generated code, I have a `\phantomsection\label\ ` for the target and a `\sphinxcrossref` before the `\DUrole`. But this might be due to different sphinx versions. My RST Syntax is the same, I only use `_` instead of `-`, but I do not believe this might be the reason. – Trendfischer Aug 13 '20 at 17:50
  • @Trendfischer - Could you please explain what you mean by "I only use `_` ..." so that I may try that approach? BTW, in case it is about the `label`, I have tried underscore `_` also (e.g. `corr_n_prev_action_capa_label`) but hasn't changed the situation. The pdf file is still not showing the hyperlinks. – shaan Aug 13 '20 at 19:03
  • @mzjn - Could you please point me to a minimal sample code with linked (cross-referenced) `.rst` source files and a **pdf** generated out of those. Thanks. – shaan Aug 13 '20 at 19:33
  • I don't have a sample that I can just point you to. I think you should edit the question. Provide a proper [mcve] with all relevant information **in the question**. The toctree and the duplicate label issue are only mentioned in comments. – mzjn Aug 14 '20 at 06:54
  • Okay now what I have done is to add the _referred to_ document `capa.rst` in the **toctree** with a `:hidden:` directive. The result is: Now the hyperlink is appearing in the generated **pdf** file. But here I am **faced with another issue** - which is - though the source file **capa.rst** is not appearing in the **html** document, I am getting the file reference in the **bookmarks section** of the pdf. – shaan Aug 14 '20 at 07:11
  • @mzjn - Added please. – shaan Aug 14 '20 at 07:41
  • OK, since you now have a new issue, you should post a new question. The solution to the original issue should be posted as an answer. – mzjn Aug 14 '20 at 08:24
  • @mzjn - Create [here](https://stackoverflow.com/q/63410353/13823230). Thanks. – shaan Aug 14 '20 at 09:41

1 Answers1

2

Thanks to @mzjn and @Trendfischer, came up with the following solution:

Using the directive :hidden: in index.rst, added the referred to file capa.rst as shown:

index.rst

.. xyz documentation master file, created by
   sphinx-quickstart on...
   You can adapt this file....

XYZ documentation
===================

.. toctree::
   :maxdepth: 2
   :caption: Help Contents:

   modules/abc.rst
   modules/definitions/define_ques_list.rst
   help_on_help.rst

.. toctree::    <= New line
   :hidden:     <= New line

   modules/definitions/capa.rst.   <= New line

With this arrangement, I am now getting the hyperlink to the called file (capa.rst) when pdf file is generated.

shaan
  • 351
  • 2
  • 15
  • 1
    The hyperllink works also without `:hidden:`; the crucial thing is that there is a reference to capa.rst in a `toctree` directive. – mzjn Aug 15 '20 at 14:19