docs: Add links and more discussion to examples. (#227)

* Added links and more discussion

* Added various links

* Update fa-examples.md

* Update fa-examples.md

* Update links in readme

* Add output to fa examples

* Fix various typos

Co-authored-by: Caleb Evans <caleb@calebevans.me>

---------

Co-authored-by: Caleb Evans <caleb@calebevans.me>

README.md

@@ -11,9 +11,11 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/automata-lib)
 [![status](https://joss.theoj.org/papers/fe4d8521383598038e38bc0c948718af/status.svg)](https://joss.theoj.org/papers/fe4d8521383598038e38bc0c948718af)
 
-- **Documentation**: https://caleb531.github.io/automata/
-- **Migration Guide**: https://caleb531.github.io/automata/migration/
-- **API**: https://caleb531.github.io/automata/api/
+Links:
+- [**Documentation**](https://caleb531.github.io/automata/)
+- [**Examples**](https://caleb531.github.io/automata/examples/fa-examples/)
+- [**Migration Guide**](https://caleb531.github.io/automata/migration/)
+- [**API**](https://caleb531.github.io/automata/api/)
 
 Automata is a Python 3 library implementing structures and algorithms for manipulating finite automata,
 pushdown automata, and Turing machines. The algorithms have been optimized and are capable of

docs/examples/fa-examples.md

@@ -1,11 +1,19 @@
 # Finite Automata Examples
 
 On this page, we give some short examples with discussion for the finite
-automata classes and methods.
+automata (sometimes called finite state machines) classes and methods in
+this package. At a high level, a finite automaton (FA) is an abstract
+machine that can be in any one of a finite number of _states_, and
+moves between states based on a _transition function_ in response to
+reading characters from an input string. The FA will _accept_ or _reject_ an
+input string depending on its current state.
 
-## Reading basic input
+For a detailed overview of this topic, see [this Wikipedia article][wikipedia-fsm]
+or [these lecture notes][lecture-notes].
 
-In this example, we define a function that takes in an automaton
+## Reading input
+
+In this example, we first define a function that takes in an automaton
 and asks the user for input strings, printing whether the input was
 accepted or rejected:
 
@@ -21,7 +29,10 @@ def read_user_input(my_automaton):
         print("")
 ```
 
-With this code in hand, let's define a DFA and see it in action:
+### Deterministic finite automaton (DFA)
+
+To use this function, let's first define a DFA.
+For a detailed definiton, see [this Wikipedia article on DFAs][wikipedia-dfa].
 
 ```python
 from automata.fa.dfa import DFA
@@ -38,14 +49,33 @@ my_dfa = DFA(
     initial_state='q0',
     final_states={'q1'}
 )
+```
+
+We can generate a picture of our DFA using the package:
+
+```python
+my_dfa.show_diagram()
+```
+
+This produces the following:
 
+![my dfa image](img/my_dfa.svg)
+
+Now that we've defined our DFA, we can see our funciton in action:
+
+```python
 read_user_input(my_dfa)
+# 001 -> Accepted
+# 011 -> Rejected
+# 000111 -> Accepted
 ```
 
+### Nondeterministic finite automaton (NFA)
+
 We can also do the same with an NFA we define. Note that the
 transition dictionary for the NFA has a different structure than
 that of the DFA, and that we are working over a different input
-alphabet than the previous example:
+alphabet than the previous example. For a detailed definiton, see [this Wikipedia article on NFAs][wikipedia-nfa].
 
 ```python
 from automata.fa.nfa import NFA
@@ -63,15 +93,32 @@ my_nfa = NFA(
     initial_state="q0",
     final_states={"q1"},
 )
+```
+
+Similar to the DFA, we can generate a picture of our NFA:
 
+```python
+my_nfa.show_diagram()
+```
+
+This produces the following:
+
+![my nfa image](img/my_nfa.svg)
+
+We can call our function as in the prior example:
+
+```python
 read_user_input(my_nfa)
+# b -> Rejected
+# aa -> Accepted
+# abaa -> Accepted
 ```
 
 ## Subset for NFAs
 
 The `NFA` does not have a built-in method for checking whether it is a subset
 of another `NFA`. However, this can be done using existing methods in the
-package. See the following function and example usages:
+package:
 
 ```python
 import string
@@ -84,14 +131,24 @@ def is_subset(nfa1, nfa2):
     # If taking the union of nfa2 with nfa1 is equal to nfa2 again,
     # nfa1 didn't accept any strings that nfa2 did not, so it is a subset.
     return nfa1.union(nfa2) == nfa2
+```
 
+To see our function in action, we need to define some NFAs. We can
+do this easily by converting from regular expressions. For more information
+about this equivalence, see [the Wikipedia article on regular languages][wikipedia-reglang]:
 
+```python
 alphabet = set(string.ascii_lowercase)
 
 nfa1 = NFA.from_regex("abc", input_symbols=alphabet)
 nfa2 = NFA.from_regex("(abc)|(def)", input_symbols=alphabet)
 nfa3 = NFA.from_regex("a*bc", input_symbols=alphabet)
+```
 
+With these NFAs, we can now call the function and check that it matches the
+expected results.
+
+```python
 print(is_subset(nfa1, nfa2))  # True
 print(is_subset(nfa1, nfa3))  # True
 print(is_subset(nfa2, nfa3))  # False
@@ -105,9 +162,6 @@ the target edit distance to a reference string. We do this by creating an
 edit distance NFA and intersecting it with a DFA recognizing our original
 set of strings:
 
-[levelshtein-article]: http://blog.notdot.net/2010/07/Damn-Cool-Algorithms-Levenshtein-Automata
-
-
 ```python
 import string
 
@@ -156,7 +210,7 @@ print(
 
 The example below is adapted from the
 [visual automata](https://github.com/lewiuberg/visual-automata) library.
-This function takes in a `DFA` or `NFA` and returns the
+This function takes in a DFA or NFA and returns the
 corresponding transition table.
 
 The start state is prefixed with `→` and final states are prefixed
@@ -209,3 +263,10 @@ def make_table(target_fa) -> pd.DataFrame:
     df = pd.DataFrame.from_dict(table).fillna("∅").T
     return df.reindex(sorted(df.columns), axis=1)
 ```
+
+[wikipedia-fsm]: https://en.wikipedia.org/wiki/Finite-state_machine
+[wikipedia-dfa]: https://en.wikipedia.org/wiki/Deterministic_finite_automaton
+[wikipedia-nfa]: https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton
+[wikipedia-reglang]: https://en.wikipedia.org/wiki/Regular_language
+[lecture-notes]: https://jeffe.cs.illinois.edu/teaching/algorithms/#models
+[levelshtein-article]: http://blog.notdot.net/2010/07/Damn-Cool-Algorithms-Levenshtein-Automata

docs/index.md

@@ -14,6 +14,12 @@ processing large inputs. Visualization logic has also been implemented. This pac
 both researchers wishing to manipulate automata and for instructors teaching courses on theoretical
 computer science.
 
+For an overview on automata theory, see [this Wikipedia article][wikipedia-article], and
+for a more comprehensive introduction to each of these topics, see [these lecture notes][lecture-notes].
+
+[wikipedia-article]: https://en.wikipedia.org/wiki/Automata_theory
+[lecture-notes]: https://jeffe.cs.illinois.edu/teaching/algorithms/#models
+
 The library requires Python 3.8 or newer.
 
 ## Installing