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] How can one create a Sphinx directive that creates documentation from an externally defined data structure?

[Doug Hellmann]

> On Jun 29, 2020, at 3:59 PM, Rollo Konig-Brock  wrote:
> 
> Hey there,
> 
> I posted this question on stack overflow, but I think it's a bit too niche 
> for that site and it's better to just ask the hardcore Sphinx users.
> 
> --
> 
> How can one create a Sphinx directive that creates documentation from an 
> externally defined data structure?
> 
> For context, I have some classes that automatically create attributes based 
> on a JSON response.
> 
> class Model:
> 
> 
> def __init__(self, json_data):
> 
> self
> .__dict__ =
>  json_data
> 
> 
> model 
> = Model({"a": 1})
> 
> model
> .a
> The issue I'm having is documenting this in Sphinx. I could possibly do it 
> manually like so:
> 
> .. autoclass:: Model
> 
> 
> 
> .. attribute:: a
> However the properties are numerous, outside my control, which presents 
> issues keeping the documentation up to date with the backend.
> 
> Attempting to remedy this problem I've built up a data-structure pulled from 
> a swagger document that contains information about these dynamic properties. 
> However I have no idea how to apply this in Sphinx. I've looked into custom 
> directives and domains, but without some serious digging into the internals I 
> don't understand how to create a directive that creates other directives.
> 
> In essence I would like to do the following.
> 
> .. autoclass:: Model
> 
> 
> 
> .. custom_set_of_attributes_directive:: model_schema

If you have the swagger data in a machine-parseable format like XML you may 
find sphinxcontrib-datatemplates useful for formatting it within a sphinx 
document. https://github.com/sphinx-contrib/datatemplates/ 

> Which would be equivalent to:
> 
> .. autoclass:: Model
> 
> 
> 
> .. attribute::
>  a
> 
> .. attribute::
>  b
> 
> .. attribute:: c
> 
> 
> -- 
> 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/58214896-735d-4b47-94d1-9ab2f907e6aeo%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/E12C5519-4646-4A3E-AA66-289D3897707F%40doughellmann.com.

Re: [sphinx-users] How can one create a Sphinx directive that creates documentation from an externally defined data structure?

[Rollo Konig-Brock]

Thanks Komiya, that's awesome. 

On Tuesday, 7 July 2020 15:14:54 UTC+1, Komiya Takeshi wrote:
>
> Hi, 
>
> AFAIK, there are no way to expand the contents for directives via own 
> custom directive. As a similar way, you can generate whole of 
> directive via own custom directive: 
>
> .. custom_set_of_attributes_directive:: Model x model_schema 
>
> Which would be equivalent to: 
>
> .. autoclass:: Model 
>
> .. attribute:: a 
> .. attribute:: b 
> .. attribute:: c 
>
> The nested_parse() will help you to implement such a feature. It 
> allows you to pass content to the parser. 
>
> ``` 
> from docutils.statemachine import StringList 
>
> class CustomSetOfAttributeDirective(Directive): 
> def run(self): 
> # generate content 
> content = StringList() 
> content.append(".. autoclass:: Model") 
> content.append("") 
> content.append("   .. attribute:: a") 
> content.append("   .. attribute:: b") 
> content.append("   .. attribute:: c") 
>
> # call nested_parse to parse content using reST parser 
> node = nodes.Element() 
> self.state.nested_parse(content, self.content_offset, node)  # 
> the result will be stored into `node`. 
>
> return node.children 
> ``` 
>
> I hope this helps you :-) 
>
> Thanks, 
> Takeshi KOMIYA 
>
> 2020年6月30日(火) 4:59 Rollo Konig-Brock >: 
> > 
> > Hey there, 
> > 
> > I posted this question on stack overflow, but I think it's a bit too 
> niche for that site and it's better to just ask the hardcore Sphinx users. 
> > 
> > -- 
> > 
> > How can one create a Sphinx directive that creates documentation from an 
> externally defined data structure? 
> > 
> > For context, I have some classes that automatically create attributes 
> based on a JSON response. 
> > 
> > class Model: 
> > def __init__(self, json_data): 
> > self.__dict__ = json_data 
> > 
> > 
> > model = Model({"a": 1}) 
> > model.a 
> > 
> > The issue I'm having is documenting this in Sphinx. I could possibly do 
> it manually like so: 
> > 
> > .. autoclass:: Model 
> > 
> > .. attribute:: a 
> > 
> > However the properties are numerous, outside my control, which presents 
> issues keeping the documentation up to date with the backend. 
> > 
> > Attempting to remedy this problem I've built up a data-structure pulled 
> from a swagger document that contains information about these dynamic 
> properties. However I have no idea how to apply this in Sphinx. I've looked 
> into custom directives and domains, but without some serious digging into 
> the internals I don't understand how to create a directive that creates 
> other directives. 
> > 
> > In essence I would like to do the following. 
> > 
> > .. autoclass:: Model 
> > 
> > .. custom_set_of_attributes_directive:: model_schema 
> > 
> > Which would be equivalent to: 
> > 
> > .. autoclass:: Model 
> > 
> > .. attribute:: a 
> > .. attribute:: b 
> > .. attribute:: c 
> > 
> > 
> > -- 
> > 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...@googlegroups.com . 
> > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/sphinx-users/58214896-735d-4b47-94d1-9ab2f907e6aeo%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/e897c893-f31a-4203-ba0f-412aa042cbf6o%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.