Adding directory for usage examples?

[caleb531]

So the API documentation reorg (#98 and #99) is complete—great! But as I look through the API documentation, I realize that there is a lot of text to sift through between each block of code.

@Tagl @eliotwrobson What do you think about adding an examples/ directory with Python files that demonstrate the code needed to perform the most common DFA/etc. operations. Since the API is so large at this point, we would probably need to be selective about what use cases we plan to demonstrate.

One option is that we could make each example built around a real-world use case. For example:

# examples/reading_input_from_cli.py
from automata.fa.dfa import DFA

# DFA which matches all binary strings ending in an odd number of '1's
my_dfa = DFA(
    states={'q0', 'q1', 'q2'},
    input_symbols={'0', '1'},
    transitions={
        'q0': {'0': 'q0', '1': 'q1'},
        'q1': {'0': 'q0', '1': 'q2'},
        'q2': {'0': 'q2', '1': 'q1'}
    },
    initial_state='q0',
    final_states={'q1'}
)

try:
    while True:
        if my_dfa.accepts_input(input('Please enter your input: ')):
            print('Accepted')
        else:
            print('Rejected')
except KeyboardInterrupt:
    print('')

Another option is that we could make each example a sort of rapid-fire walkthrough of the different things you can do. For example:

# examples/dfa_reading_input.py
from automata.fa.dfa import DFA

# DFA which matches all binary strings ending in an odd number of '1's
my_dfa = DFA(
    states={'q0', 'q1', 'q2'},
    input_symbols={'0', '1'},
    transitions={
        'q0': {'0': 'q0', '1': 'q1'},
        'q1': {'0': 'q0', '1': 'q2'},
        'q2': {'0': 'q2', '1': 'q1'}
    },
    initial_state='q0',
    final_states={'q1'}
)

my_dfa.read_input('001') # returns a final state (e.g. 'q1')

my_dfa.read_input('001!') # raises RejectionException

# loop over each state of the DFA as you read input
for state in my_dfa.read_input_stepwise('00111'):
    print(state)

# etc.

We may also need to be careful of adding too many examples, such that it becomes an additional maintenance burden on top of the existing API documentation. But it might be helpful for beginners. I'm a bit ambivalent—what do you think?

[eliotwrobson]

@caleb531 I think this is a good idea for a few basic examples. I think they're easier to write given the new DFA construction algorithms. I don't think the maintenance burden will be too much if the examples are kept simple (since I don't expect the API to change a ton after v7).

[eliotwrobson]

Good idea for an example: subset checking for NFAs. This would be the same logic used for the regex subset checking. Also playing with the edit distance automata and finite languages (which has been the subject of some blog posts).

[eliotwrobson]

@caleb531 looking over this again, do you think a directory would be preferable to a docs page that has a bunch of rapid-fire snippets on it? I'm kinda leaning towards that, since most of the examples that have been listed here are relatively short, and it would be good to integrate them with some commentary and let people easily view them within the rest of the docs instead of having to look at a bunch of separate files.

[caleb531]

@eliotwrobson Hm, that's a noteworthy idea. By a "docs page", do you mean something like an examples.md file inside each doc subfolder (e.g. fa/examples.md, pda/examples.md, etc.)?

I like the idea of having the examples somewhere under docs/, for sure.

[eliotwrobson]

Yes, just a file with a few short examples written down.

[caleb531]

@eliotwrobson That sounds good to me! I'd say go for it, if you have time.

[eliotwrobson]

@caleb531 Since we added FA examples, do we want to go ahead and close this issue? I think the examples are probably the most relevant for the FA classes, since there aren't too many sophisticated methods for the TM / PDA classes that warrant the inclusion of example code right away.

[caleb531]

@eliotwrobson Yeah, I think that's fine. We can always open a new issue for PDA/TM examples. But at the moment, this seems good for now.