Is the _toc.yml format here up to date?

[Sparrow0hawk]

Tried using this for SWD5 repo and hit some errors so wondering if the _toc.yml requires an update for newer versions of Jupyter book.

Updated:

• Submit a PR that aligns the _toc.yml in this repository with HPC2 i.e. using format: jb-article rather than format: jb-book

[Sparrow0hawk]

Okay so trying to reproduce my issue here.

I was also looking at our HPC2 repository and there we have format: jb-article rather than the default here of format: jb-book.

I changed that when I started migrating SWD5 repo and immediately hit the following error when running jb build book/:

$ jb build book/
Running Jupyter-Book v0.13.0
Source Folder: /workspaces/template-jb-docs/book
Config Path: /workspaces/template-jb-docs/book/_config.yml
Output Path: /workspaces/template-jb-docs/book/_build/html
Running Sphinx v4.5.0
[etoc] Changing master_doc to 'welcome'
loading pickled environment... done
myst v0.15.2: MdParserConfig(renderer='sphinx', commonmark_only=False, enable_extensions=['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'], dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], url_schemes=['mailto', 'http', 'https'], heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] welcome                                                                                                                               
looking for now-outdated files... none found
pickling environment... done
checking consistency... /workspaces/template-jb-docs/book/example_section/start.md: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] welcome                                                                                                                                
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in book/_build/html.

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

Finished generating HTML for book.
Your book's HTML pages are here:
    book/_build/html/
You can look at your book by opening this file in a browser:
    book/_build/html/index.html
Or paste this line directly into your browser bar:
    file:///workspaces/template-jb-docs/book/_build/html/index.html            

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

(arcdocs-jb) @Sparrow0hawk ➜ /workspaces/template-jb-docs (main) $ jb build book/
Running Jupyter-Book v0.13.0
Traceback (most recent call last):
  File "/opt/conda/envs/arcdocs-jb/bin/jb", line 8, in <module>
    sys.exit(main())
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/jupyter_book/cli/main.py", line 244, in build
    parse_toc_yaml(toc)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/sphinx_external_toc/parsing.py", line 88, in parse_toc_yaml
    data = yaml.safe_load(handle)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/__init__.py", line 125, in safe_load
    return load(stream, SafeLoader)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/__init__.py", line 81, in load
    return loader.get_single_data()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/constructor.py", line 49, in get_single_data
    node = self.get_single_node()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 36, in get_single_node
    document = self.compose_document()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 55, in compose_document
    node = self.compose_node(None, None)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 84, in compose_node
    node = self.compose_mapping_node(anchor)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 133, in compose_mapping_node
    item_value = self.compose_node(node, item_key)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 82, in compose_node
    node = self.compose_sequence_node(anchor)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 111, in compose_sequence_node
    node.value.append(self.compose_node(node, index))
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 84, in compose_node
    node = self.compose_mapping_node(anchor)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/composer.py", line 127, in compose_mapping_node
    while not self.check_event(MappingEndEvent):
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/parser.py", line 98, in check_event
    self.current_event = self.state()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/parser.py", line 428, in parse_block_mapping_key
    if self.check_token(KeyToken):
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/scanner.py", line 116, in check_token
    self.fetch_more_tokens()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/scanner.py", line 223, in fetch_more_tokens
    return self.fetch_value()
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/yaml/scanner.py", line 577, in fetch_value
    raise ScannerError(None, None,
yaml.scanner.ScannerError: mapping values are not allowed here
  in "/workspaces/template-jb-docs/book/_toc.yml", line 10, column 11
(arcdocs-jb) @Sparrow0hawk ➜ /workspaces/template-jb-docs (main) $ jb build book/
Running Jupyter-Book v0.13.0
Traceback (most recent call last):
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/jupyter_book/cli/main.py", line 244, in build
    parse_toc_yaml(toc)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/sphinx_external_toc/parsing.py", line 89, in parse_toc_yaml
    return parse_toc_data(data)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/sphinx_external_toc/parsing.py", line 114, in parse_toc_data
    doc_item, docs_list = _parse_doc_item(
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/sphinx_external_toc/parsing.py", line 170, in _parse_doc_item
    raise MalformedError(
sphinx_external_toc.parsing.MalformedError: Unknown keys found: {'chapters'}, allowed: {'options', 'title', 'meta', 'root', 'format', 'sections', 'subtrees', 'defaults'} @ '/'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/conda/envs/arcdocs-jb/bin/jb", line 8, in <module>
    sys.exit(main())
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/jupyter_book/cli/main.py", line 246, in build
    _error(
  File "/opt/conda/envs/arcdocs-jb/lib/python3.8/site-packages/jupyter_book/utils.py", line 48, in _error
    raise kind(box)
RuntimeError: 
===============================================================================

The Table of Contents file is malformed: Unknown keys found: {'chapters'}, allowed: {'options', 'title', 'meta', 'root', 'format', 'sections', 'subtrees', 'defaults'} @ '/'
You may need to migrate from the old format, using:

        jupyter-book toc migrate /workspaces/template-jb-docs/book/_toc.yml -o /workspaces/template-jb-docs/book/_toc.yml

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

This appears to just be me not understanding the Jupyter Book formats, jb-book has chapters whilst jb-article does not. Removing the chapters key in the yml and just using sections resolved this problem.

But that leads on to a more general point. Should our template _toc.yml here be using jb-article over jb-book?

[jhodrien]

I think it should use the format we most expect to be using. If that appears to be jb-article, then I think we should change the template to match.

[Sparrow0hawk]

Adding a task to this issue