Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Is the _toc.yml format here up to date? #4

Open
1 task
Sparrow0hawk opened this issue Apr 18, 2023 · 3 comments
Open
1 task

Is the _toc.yml format here up to date? #4

Sparrow0hawk opened this issue Apr 18, 2023 · 3 comments
Labels
enhancement New feature or request good first issue Good for newcomers

Comments

@Sparrow0hawk
Copy link
Contributor

Sparrow0hawk commented Apr 18, 2023 •
edited
Loading

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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor Author

Adding a task to this issue

@Sparrow0hawk Sparrow0hawk added enhancement New feature or request good first issue Good for newcomers labels Apr 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request good first issue Good for newcomers
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@jhodrien @Sparrow0hawk