Developing Flutter Implements for Jupyter Book and MyST Markdown

[Guo-Zhang]

Dear Executable Book Team,

I am willing to contribute Flutter package for Jupyter Book and MyST Markdown. Here is the repositories from my team.

• Flutter Jupyter Book: https://github.com/quanttide/flutter-jupyterbook
• Flutter MyST Markdown: https://github.com/quanttide/flutter-myst-markdown

I am developing an online programming learning APP with Flutter. I use Jupyter Book to document all the tutorials, and deploy it to the backend of APP by code. I want to parse the MyST Markdown and Jupyter Book, so I am developing these packages.

In addition, I have read the source code of Jupyter Book, since there are a lot of unclear exceptions. To be honest, it is not well organized, so I am also willing to help you on that. It also affects the secondary development of my own backend tools.

If you are interested in that, be free to contact with me (zhangguo@quanttide.com).

Sincerely,
Guo Zhang

[chrisjsewell]

Hi Guo, thanks for your interest! So are your plans to actually write a full MyST Markdown parser in Dart?

there are a lot of unclear exceptions .. to be honest, it is not well organized

I would certainly be interested to get your feedback on some specific issues you had, and what could be made clearer?

[Guo-Zhang]

Yes, a Dart parser and a Flutter render. Writing The Dart parser needs to understand how the MyST Markdown is parsed. The Flutter render needs to define a way to run code and render the result.

build command only returns RuntimeError. For example, if we don't config the title for a article, it will return:

reading sources... [ 66%] 1_example_chapter/README                                                                                                      
Exception occurred:
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx_external_toc/events.py", line 294, in insert_toctrees
    doctree.children[-1].extend(node_list)
IndexError: list index out of range
The full traceback has been saved in /var/folders/l2/vb61_vhd5r3gc1fxchg_32jw0000gn/T/sphinx-err-sn69ts_0.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Traceback (most recent call last):
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/jupyter_book/sphinx.py", line 167, in build_sphinx
    app.build(force_all, filenames)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/application.py", line 330, in build
    self.builder.build_update()
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 286, in build_update
    self.build(to_build,
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 300, in build
    updated_docnames = set(self.read())
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 407, in read
    self._read_serial(docnames)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 428, in _read_serial
    self.read_doc(docname)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 468, in read_doc
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/io.py", line 181, in read_doc
    pub.publish()
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/docutils/core.py", line 219, in publish
    self.apply_transforms()
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/docutils/core.py", line 200, in apply_transforms
    self.document.transformer.apply_transforms()
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx/transforms/__init__.py", line 79, in apply_transforms
    super().apply_transforms()
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms
    transform.apply(**kwargs)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx_external_toc/events.py", line 307, in apply
    insert_toctrees(self.app, self.document)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/sphinx_external_toc/events.py", line 294, in insert_toctrees
    doctree.children[-1].extend(node_list)
IndexError: list index out of range

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/zhangguo/.pyenv/versions/3.9.9/bin/jupyter-book", line 8, in <module>
    sys.exit(main())
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/click/core.py", line 829, in __call__
    return self.main(args, *kwargs)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/click/core.py", line 610, in invoke
    return callback(args, *kwargs)
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 323, in build
    builder_specific_actions(
  File "/Users/zhangguo/.pyenv/versions/3.9.9/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 535, in builder_specific_actions
    raise RuntimeError(_message_box(msg, color="red", doprint=False)) from result
RuntimeError: 
===============================================================================

There was an error in building your book. Look above for the cause.

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

[Guo-Zhang]

Updated:

I have released a MVP: https://pub.dev/packages/flutter_myst_markdown, and use it in my application:
https://class.quanttide.com/courses/programming-with-python/lectures/hello-world

Hope to corporate with the community to develop this package!

Sincerely,
QuantTide Inc.