docs: add teaching example

[phildong]

I have never taken a formal CS class so it's a bit hard for me to imagine how automata can actually be used in class. Since one of the major purpose of this package is for education, I feel it's beneficial to include some examples of the most basic usage of the package in the context of teaching. I have included an initial draft illustrating this idea in the PR.

I think it's also a good idea to expand this to include all major functionality of the package, preferably in a continuous pipeline rather than isolated snippets. I've included building, running and visualizing the automaton so far, but it will be great to have other examples cover other use cases I missed. Right now the examples in the documentation feels like a short list of specific interesting functions you can play with, and it's hard for me to grasp in general the breadth of stuff I can do with automata package.

[coveralls]

coverage: 99.64%. remained the same when pulling ae6eeb2feb28918790b22b016c76a7afe8472f12 on phildong-reviews:teaching_exp into 13e5c1b5bf1d92522eb83e914ad946552b77aaf7 on caleb531:main.

[coveralls]

coverage: 99.64%. remained the same when pulling ae6eeb2feb28918790b22b016c76a7afe8472f12 on phildong-reviews:teaching_exp into 13e5c1b5bf1d92522eb83e914ad946552b77aaf7 on caleb531:main.

[caleb531]

I definitely like the idea in principle, and think this represents a start in the right direction! @eliotwrobson, since you have a much stronger education background (let alone active experience), I would love to hear your thoughts on these examples (when you have time).

[eliotwrobson]

@caleb531 I think having some self-contained examples would be a substantial benefit. I don't think it can quite rise to the level of a self-guided textbook or anything like that (learning all of the models we implement in this package is about the scope of a one semester course), but it might be possible to have a notebook or examples on the site that have short introductions to these models.

[eliotwrobson]

@caleb531 After taking another look at this, I think if we want something more self-contained, one possible direction would be to follow Jeff Erickson's notes on models of computation: https://jeffe.cs.illinois.edu/teaching/algorithms/#models

We can have shorter text descriptions and refer back to the notes directly. It might be better to do this in a jupyter notebook than directly on the docs page, but I definitely prefer to allow people to access the examples without having to run anything locally (leaving that as an option).

Edit: could include an example about this: https://arxiv.org/abs/1004.1298

[caleb531]

@eliotwrobson Just now getting back to this: I don't have too many ideas in terms of the ideal direction, but in general, I'm open to what is most practical and useful for people to learn automata.

At first, I was going to suggest a why-not-both approach of both notebooks and on the docs page. But I can see that potentially becoming a maintenance burden by effectively having two separate copies of the material.

Maybe there's a way that Jupyter notebooks can be exported to PDF or Markdown or to some non-interactive form that could be embedded in the docs page (so we can consolidate the material)? I'm not too familiar with Jupyter notebooks personally, so I may not be making any sense here lol. But just wanted to give my two cents.

[eliotwrobson]

Maybe there's a way that Jupyter notebooks can be exported to PDF or Markdown or to some non-interactive form that could be embedded in the docs page (so we can consolidate the material)?

@caleb531 in fact, there is!: https://github.com/danielfrg/mkdocs-jupyter

I haven't played with this extension but setting it up seems straightforward.

[phildong]

Just want to chime in and say I think all of these sounds like potentially good directions! Also want to say I was not proposing documentation on learning automata at all, but rather how the automata library can be used to give some quick demonstration in a teaching situation. So I think a short, self-contained example, with a tiny bit of background concepts (could be links to wikipedia or any other materials mentioned in this thread), would suffice and actually preferable to a longer, more comprehensive introduction to computation theory.

[eliotwrobson]

Closing since our examples on the develop branch have been updated, and more comprehensive tutorials are coming later. Thanks again for the suggestions and discussions raised here!