Using rst file names for navigation

[Bradley Bell]

I only use one heading at the top level for each file.
The file name (without the .rst extansion) is a shorthand for the heading at the top of each file.

I would like to use the file names, and only the file names in the navigation tree.
The navigation for a section would show its children, and possible grandchilren, down to some configurable level.

It would also be nice for the navigation to also show all the ancestors above the current section; i.e.,

the position of the current web page in the documentaion tree (using the file names).

I currently do this with links at the top of each section; e.g.,

   grand_parent > parent > current

where grand_parent, parent, and current are the corresponding file names and grand_parent and parent are links.

How do I do this using sphinx ?

[Matt from Documatt]

Hi Bradley!

Question #1 - You can't use filename as document title. First section found in document will become a document title.

Baz will be document title:

foo

bar

baz

===

but document title is usually at the very top of the file:

baz

===

foo

bar

Question 2 - you speak about breadcrumb navigation. If you have correctly described relations among documents using toctree directive, many themes use breadcrumb > like > you > mention. Important here is to emphasize that structure of book is described with toctree directive, not with on-disk representation of document files.

Matt

blog.documatt.com

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/284685c5-9204-4ebf-bbe5-f505b01475bfo%40googlegroups.com.

[bradley...@gmail.com]

I have been using my own documentation system for years and am writing a program to convert sphinx so that it is easier for others to edit my documentation, and so that I no longer have to maintain it (It was written years ago in C).  In this system one has a title and an abbreviated title for each section (web page) and the abbreviated titles are used for navigation.

Here is an example use of my documentation system:
https://bradbell.github.io/dismod_at/doc/data_table.py.htm

I am asking how to best reproduce this navigation functionality in sphinx ?

[Stefano David]

HI,

On Wednesday, 8 July 2020 13:23:02 UTC+2, bradley...@gmail.com wrote:

I have been using my own documentation system for years and am writing a program to convert sphinx so that it is easier for others to edit my documentation, and so that I no longer have to maintain it (It was written years ago in C).  In this system one has a title and an abbreviated title for each section (web page) and the abbreviated titles are used for navigation.

Here is an example use of my documentation system:
https://bradbell.github.io/dismod_at/doc/data_table.py.htm

I am asking how to best reproduce this navigation functionality in sphinx ?

If I understand correctly your requirement, given that you have files first.rst, second.rst, third.rst you should be able to add them to the toctree as follows to get the desired effect:

.. toctree::

   first.rst <first>

   second.rst <second>

   third.rst <third>

HTH,

Stefano

[bradley...@gmail.com]

I am using toctree in each section that has children as you describe above. When I view the section with that toctree entry, I would like the navigation links in the left column to corresponds to the names in the toctree command; i.e., use 'first' instead of the headings in the file first.rst, 'second' instead of the headings in section.rst, and so on.

Right now, I get all the headings in the root section of my entire document, instead of the bread crumb file names up to the root section and the children below.

[bradley...@gmail.com]

I have figured out a solution to my problem.  I put an extra header at the top of every file that is the rst file name without extension. I also use the following setting in my conf.py file:

html_theme = 'sphinx_rtd_theme'

html_theme_options = {
    'navigation_depth' : -1   ,
    'titles_only'      : True ,

}

For an example of the result; see
https://bradbell.github.io/cppad_py/doc/html/xsrst/cppad_py.html

This uses the xsrst program which extras sphinx rst files from source code; see
https://bradbell.github.io/cppad_py/doc/html/xsrst/xsrst_py.html

[Daniel Scott]

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/91f64845-dc92-4617-8d91-6796dee19995n%40googlegroups.com.