Jupyter-book: Create a `tableofcontents` directive

[choldgraf]

Right now we define the book's table of contents in _toc.yml, but sometimes you also want to show the table of contents within the content of the page. By default we can't do this in Sphinx without also altering the table of contents, but we could pretty easily support a directive that just shows the table of contents for the book.

[choldgraf]

cc @jstac who was discussing this in another issue

[najuzilu]

There's a contents directive in Sphinx
```{contents} Table of Contents :depth: 2 ```
which looks like this in our quantecon-example:

In the quantecon-example we use headers to give the illusion of the following structure - but it's really a flat structure:

• Introduction to Python
  
  
  
  • about_py
  
  
  • getting_started
  
  
• Scientific Libraries
  
  
  
  • need_for_speed
  
  
  • numpy
  
  
• Advanced Python
  
  
  
  • writing_good_code
  
  

I think it's a good idea for the tableofcontents -or simply contents if we want to override sphinx's directive- to display this as is shown on the sidebar.

[choldgraf]

I'm +1 on a new directive, I don't think we want to clobber the Sphinx directive

[choldgraf]

Another option here, that might a bit less complicated, is to do the following:

In _toc.yml allow for a key like show_toc: true when pointing to a file. This would tell Jupyter Book to include the toctree output in the page instead of using :hidden:.

and maybe in addition, support something like "if a page has the text {tableofcontents} then Jupyter Book will place the {toctree} directive there instead of at the end of the page

[AakashGfude]

@choldgraf Was trying to return a {toctree} node with all the docnames wherever {tableofcontents} directive is written.
Was getting maximum recursion depth exceeded , probably because of circular reference somewhere. I will look at that.

So, according to your suggestion, should continue with that, and in addition have the _toc.yml explicitly declare in which page the tableofcontents is gonna be, by giving a key show_toc: true along with the -file key ?

cc: @mmcky @najuzilu

EDIT got the issue, the index file was causing it, ofcourse

[choldgraf]

We don't necessarily need a {toctree} node - Sphinx tends to do special things with those nodes...we just need the list of pages + links.

Do you all think a good short-term solution would be something like a :show_toc: option in the _toc.yml file? So:

- file: myfile
  show_toc: true
  sections:
    - file: page1
    - file: page2

would show the toctree object that is inserted into myfile?

[AakashGfude]

@choldgraf I am a bit confused about :show_toc: option, and that it will _show_ the toctree object inserted .
So, the user would have to write tableofcontents directive delacration in myfile. And to actually show it, he has to declare :show_toc: in _toc.yml?

[choldgraf]

What I meant was that currently, jupyter-book uses _toc.yml to add a {toctree} directive to each page, at the very end. By default, it adds a :hidden: flag to it so that it won't show. But if we wanted one to show on the page instead, in _toc.yml we could use something like :show_toc: and, when the {toctree} directive is added it would not have :hidden: added. But, if we have our own directive like {tableofcontents} then I don't think it'd be needed to use _toc.yml for this

[AakashGfude]

Ooh ok. I didn't know that jupyter-book adds a {toctre} directive on each page in the end. Interesting.
Also, Since, we are adding it in MyST-NB, we we will have to make it considering that people might use MyST-NB on their own project repos without using jupyter-book right?

[choldgraf]

Yeah... Though is there a reason outside of jupyter book that someone would want to insert a toc into a page without also using that toctree to define the site structure? Jupyter book needs it because it defines the site structure with toc.yml, but that's not the case with a sphinx site

[AakashGfude]

Hmm. you have got a solid point there.

[lesteve]

I guess this can be closed since the tableofcontents directive has been created in #553 ?

[choldgraf]

Yes! And we can take discussion on your new issue about the depth 👍