1

I'm using sphinx and I created multiple rst files to organize my documents. I used .. include:: <filepath/filename.rst> to include multiple rst files into one config file but when using :ref:`<reference>` this maintains the file name header label but when I click the link it isolates the page but I want it to scroll to the reference in the same page. When I use <reference>_ this will scroll to the area within the same document but no longer keeps the header label. Is there a way I can keep the reference header label and scroll within the same page while still keeping the the docs in different files?

index.rst

Welcome to testing's documentation!
===================================

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

    test/config

test/config.rst

.. title:

Hello moto
==========

Using ref maintains header

* :ref:`ref-nested`

Using underscore doesn't maintain header

- nested_

.. include:: nested_test/file.rst

.. include:: nested_test/anotherfile.rst

test/anotherdir/file.rst

.. _nested:

I'm a nested header
-------------------

Hi I'm the created nested header

test/anotherdir/anotherfile.rst

.. _ref-nested:

I'm the ref nested header
-------------------------

I'm the ref nested header

enter image description here

As you see below the first link(:ref:) maintains the header given but if you click it, it will go to an isolate page. The second link doesn't maintain the header give but uses the actual reference but if clicked it will stay on the same page and would move within the document.

Below are two images, when using :ref: it loads the page as an isolated rst file.

enter image description here

I want the link to scroll down as if within the document. enter image description here

Joseph Nguyen
  • 74
  • 8
  • What do you mean by "go to an isolate page"? – mzjn Dec 24 '19 at 10:44
  • Hi @mzjn , I went ahead and updated the question. What I meant by an isolate page is that when I use the ```.. include::``` it includes another doc within the rst file but when I mean when I say isolated page is that instead of if scrolling down when click the link. It loads the page as a separate document/view. Instead of scrolling down in the whole document. – Joseph Nguyen Dec 24 '19 at 19:22

2 Answers2

2

If I understand what you want, you can move the target and its header from the included file into the main file.

.. title:

Hello moto
==========

Using ref maintains header

* :ref:`ref-nested`

Using underscore doesn't maintain header

- nested_

.. _nested:

I'm a nested header
-------------------

.. include:: nested_test/file.rst

.. _ref-nested:

I'm the ref nested header
-------------------------

.. include:: nested_test/anotherfile.rst

This has an added benefit that if you include your included files in more than one file, then you can specify a unique target and avoid Sphinx errors.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
1

I found the answer I wanted on a different stack overflow question here. I don't have to create a reference if it's in the same file using include I can reference the title itself. Refer to the link and see @Baleb answer.

How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?

Joseph Nguyen
  • 74
  • 8