Re: [sphinx-users] Using rst file names for navigation

[Daniel Scott]

On Fri, Jul 24, 2020, 3:27 PM bradley...@gmail.com 
wrote:

> 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
>
>
> On Wednesday, July 8, 2020 at 11:24:28 AM UTC-7 bradley...@gmail.com
> wrote:
>
>> 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.
>>
>>
>>
>> On Wednesday, July 8, 2020 at 6:52:43 AM UTC-7 Stefano David wrote:
>>
>>> 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 
>>>second.rst 
>>>third.rst 
>>>
>>> HTH,
>>> Stefano
>>>

 On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt
 wrote:

> 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
>
> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell 
> wrote:
>
>> 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 ?
>>
>> --
>> 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
>> 
>> .
>>
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-users" group.
> To unsubscribe from this group and stop 

Re: [sphinx-users] Using rst file names for navigation

[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


On Wednesday, July 8, 2020 at 11:24:28 AM UTC-7 bradley...@gmail.com wrote:

> 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.
>
>
>
> On Wednesday, July 8, 2020 at 6:52:43 AM UTC-7 Stefano David wrote:
>
>> 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 
>>second.rst 
>>third.rst 
>>
>> HTH,
>> Stefano
>>
>>>
>>> On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:
>>>
 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

 On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  
 wrote:

> 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 ? 
>
> -- 
> 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
>  
> 
> .
>


-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 

Re: [sphinx-users] Using rst file names for navigation

[Daniel Scott]

Please return my information on navigation Using file so contact me with
further response  my contact email is : dan.scott@usa.com please
contact  me further project material .Thank you

On Tue, Jul 7, 2020, 11:47 AM Bradley Bell  wrote:

> 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 ?
>
> --
> 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+unsubscr...@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
> 
> .
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/CAELGjd_Y0cHht%3D45tzSk75jH5n9h%3DLOEpmMs4U%3D6RFzOe_Hxdw%40mail.gmail.com.

Re: [sphinx-users] Using rst file names for navigation

[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.



On Wednesday, July 8, 2020 at 6:52:43 AM UTC-7 Stefano David wrote:

> 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 
>second.rst 
>third.rst 
>
> HTH,
> Stefano
>
>>
>> On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:
>>
>>> 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
>>>
>>> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  
>>> wrote:
>>>
 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 ? 

 -- 
 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
  
 
 .

>>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/7bd70665-adce-4644-8bd6-070b76897199n%40googlegroups.com.

Re: [sphinx-users] Using rst file names for navigation

[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 
   second.rst 
   third.rst 

HTH,
Stefano

>
> On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:
>
>> 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
>>
>> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  wrote:
>>
>>> 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 ? 
>>>
>>> -- 
>>> 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
>>>  
>>> 
>>> .
>>>
>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/38c23e5e-8615-4d37-9083-956de54057aao%40googlegroups.com.

Re: [sphinx-users] Using rst file names for navigation

[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 ?

On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:

> 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
>
> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  wrote:
>
>> 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 ? 
>>
>> -- 
>> 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
>>  
>> 
>> .
>>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/a2d4e685-1353-4d51-809f-df42398c353bn%40googlegroups.com.

Re: [sphinx-users] Using rst file names for navigation

[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

On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell 
wrote:

> 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 ?
>
> --
> 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+unsubscr...@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
> 
> .
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/CAOGNDW_ZS6o0x17JgCoN7aWR7HiHNz-cJYbLB3Pra2iPOy%3DQyA%40mail.gmail.com.

[sphinx-users] 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 ? 

-- 
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+unsubscr...@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.