_toc.yml parts and chapters

[rillonline]

I have just started to use Jupyterbook on Debian Buster. I am unable to build a table of contents using parts. I have read the documentation here.
https://jupyterbook.org/customize/toc.html#structure-book
If I am understanding this correctly, "parts:" is is used only once in
the _toc.yml file. - caption: repeats to give the title of each part
and chapters: indicates a list of files for each chapter will follow
with the format: - file: filename. But this isn't working.
I can create a book with chapters but not parts and chapters.
I am usingJupyter-Book v0.11.2and Sphinx v3.5.4 which is what pip
installed on my system.
I am a writer not a python coder so I can tell you little about my python environment except to say its 3.7..
I am probably missing something very simple but I would like to get this working.

[choldgraf]

It's helpful if you post an example of the TOC that doesn't work, can you do so?

[rillonline]

Of course.

# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html

format: jb-book
root: index
parts:
- caption: Part 1
chapters:
- file: note-to-the-reader
- caption: Part 2
chapters:
- file: b01file01
- file: b01file02
- file: b01file03
- file: b01file04
- caption: Part 3
chapters:
- file: thoughts-on-the-first-adventure
- file: glossary

Everything is left justified.

[choldgraf]

thanks - what kind of error message are you getting?

[chrisjsewell]

Everything is left justified.

Heya, I'm not quite sure why you chose to left justify everything, but yeh it should look like this:

format: jb-book
root: index
parts:
- caption: Part 1
  chapters:
  - file: note-to-the-reader
- caption: Part 2
  chapters:
  - file: b01file01
  - file: b01file02
  - file: b01file03
  - file: b01file04
- caption: Part 3
  chapters:
  - file: thoughts-on-the-first-adventure
  - file: glossary

[rillonline]

I left justified everything because it is easier for me to read. I am blind and so the indentations don't provide visual clues.!
Here is what I get when I run jb.
rill@penguin:~/StarRunnerAdventures$ jb build ~/StarRunnerAdventures/
Running Jupyter-Book v0.11.2
Traceback (most recent call last):
File "/usr/local/lib/python3.7/dist-packages/jupyter_book/cli/main.py", line 243, in build
parse_toc_yaml(toc)
File "/usr/local/lib/python3.7/dist-packages/sphinx_external_toc/parsing.py", line 82, in parse_toc_yaml
return parse_toc_data(data)
File "/usr/local/lib/python3.7/dist-packages/sphinx_external_toc/parsing.py", line 101, in parse_toc_data
data, defaults, "/", depth=0, is_root=True, file_format=file_format
File "/usr/local/lib/python3.7/dist-packages/sphinx_external_toc/parsing.py", line 155, in _parse_doc_item
f"Both '{subtrees_key}' and '{items_key}' found @ '{path}'"
sphinx_external_toc.parsing.MalformedError: Both 'parts' and 'chapters' found @ '/'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/usr/local/bin/jb", line 10, in
sys.exit(main())
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1137, in call
return self.main(*args, **kwargs)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1062, in main
rv = self.invoke(ctx)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1668, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1404, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 763, in invoke
return __callback(*args, **kwargs)
File "/usr/local/lib/python3.7/dist-packages/jupyter_book/cli/main.py", line 246, in build
f"The Table of Contents file is malformed: {exc}\n"
File "/usr/local/lib/python3.7/dist-packages/jupyter_book/utils.py", line 48, in _error
raise kind(box)
RuntimeError:

The Table of Contents file is malformed: Both 'parts' and 'chapters' found @ '/'
You may need to migrate from the old format, using:

jupyter-book toc migrate /home/rill/StarRunnerAdventures/_toc.yml -o /home/rill/StarRunnerAdventures/_toc.yml

===============================================================================

rill@penguin:~/StarRunnerAdventures$

[chrisjsewell]

I am blind and so the indentations don't provide visual clues.!

Ah yes indeed that makes things a little tricky 😬, but yes the YAML format requires certain indentations to define how the elements are nested: files are in chapters, and chapters are in parts

[rillonline]

I can work with that. Is there a particular indentation scheme such as level 1 info at the left like format, root and parts? Would captions be more indented, chapters indented from there and files indented from chapters? As I understand it, I'm basically building an outline. If I wanted to number the middle part, where would that go and how would that fit into the indentation scheme?
Thanks for putting this into words. A picture (or in this case, an example) is worth a thousand words but words help me a lot.

[rillonline]

This is now working properly. Thanks for your help.

[chrisjsewell]

Ok great thanks 😄
I didn't have time to respond to your other post, but certainly let me know if you need any more explanation, and indeed anything more we can improve in the area of visual impairment

[rillonline]

It would be helpful if the documentation mentioned indenting lines or treating the table of contents like an outline. The organization is very markdown/rst-like. Your answer above is probably the one to be marked as the answer to this thread.
If anyone is interested, all the major platforms have their own builtin screen readers: Windows, Mac, Android, iOS and, of course, Linux though you may have to install orca first.