Several suggestions on EBP

[Guo-Zhang]

Hi EBP commitee,

We have used Jupyter Book and MyST Markdown as the documentation standard of my company. For example, our Python programming learning application, QtClass, write a Flutter UI to render JB doc project and myst markdown, see demo:

https://class.quanttide.com/courses/programming-with-python/lectures/python-as-calculator

Therefore, we(QuantTide Inc.) would like to join in the project. We can participate in following projects.

At first, we would like to donate our Flutter project to EBP. We find that it is difficult to develop it without cooperating with EBP.

The project is:

• https://github.com/quanttide/flutter-myst-markdown
• https://pub.dev/packages/flutter_myst_markdown

we would like to transfer the owner right to EBP.

Second, we would like to help on refactoring JB and MyST Python package. We find that there are no design patterns in the current projects, and it is very difficult when we try to extend it (we call it "QuantTide Doc Specification"). If you are interested in, we would like to discussion it with you.

Finally, we would like to help you to introduce it to Chinese developers community.

If you are interested in, we would like to discuss with you on detailed ideas.

Sincerely,
Guo Zhang, on behalf of QuantTide Inc.

[chrisjsewell]

Heya, I would check out https://myst-tools.org/docs/spec

I would suggest the best way to interact with the project is to develop your tool according to the spec, and then look to help us improve this spec, such that multiple different applications (jupyterlab book, flutter UI, …) are able to work with it

[Guo-Zhang]

Thanks for this link.

That's what we want to discuss with you. We find that this spec is not friendly to application when the frontend and backend are split. Are there any discussions on that?

[chrisjsewell]

Not to my knowledge, it would be great if you could provide a brief write-up of why you feel this is problematic with the current spec, and what the changes might look like to achieve this

[Guo-Zhang]

At first, the executive code is not clearly defined in the documentation. Currently we use directive {code-cell} to parse. But in the Jupyter Book docs, the kernel are required to be set. In addition, when the code should be executed by a remote API, it is difficult to define a standard way to deal with it. We tried our best to keep consistent with the EBP MyST Markdown spec.

For other client framework like Flutter, it is difficult to keep consistent with the Jupyter Book UI, since there is also no clear standard for that. The widgets should be defined, so that other clients can keep similar design.

[chrisjsewell]

We definitely welcome you participating in the project though 😄

[Guo-Zhang]

We find that it is difficult to develop it with ourselves, since the API documentation and source code are not well organized. Therefore, it spends a lot of time for us to write parsers once again. We have writen it in: https://quanttide.coding.net/public/quanttide-document-engineering/quanttide-docs-python/git/files. Therefore, I hope to discuss with you with that.

We have tried our best to write the parser by our own in the Flutter package. And we don't plan to maintain it in the future, so we hope to donate it to the community, so that more developers can use it in the future.

We understand that we need to do something to be trusted. We are willing to do something at first.

[Guo-Zhang]

For the Python jupyter-book, we suggest to define some domain models, like Builder, so that we can extend our own spec or builders. The customization of spec is important for advanced developers.

We also notice that the exceptions are not clearly defined, so most exceptions do not show the real problem. We find that there are some todo on that. So we would like to discuss with you on that.

[Guo-Zhang]

In addition, it is not a good engineering behavior to write the code in one main module. (jupyter-book/cli/main.py) It is not friendly for extending it.

[chrisjsewell]

Thanks, I'm going offline now, so will reply later