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 ([email protected]).

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.