improve the docstrings in the finite state machines module

[dkrenn]

The aim of this ticket is to collect various improvements to the docstring of the finite state machines module.

[dkrenn]

Last 10 new commits:

​adf99b3	updated AUTHOR-section
​511883c	state-hooks explained
​f6e5189	rewrite first few examples to avoid FSMState/FSMTransition
​ad847f8	Corrected a few typos
​97fe1b6	finite_state_machine: added a few internal hyperlinks to documentation
​680d0a6	FSMState: Documentation for attribute is_initial added
​4442ce3	finite_state_machine.py: Started TOC for documentation
​4b66e84	TOC now lists all methods and attributes
​f2c3d64	document attribute on_duplicate_transition
​7944470	inserted/removed spacings and empty lines

[git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

​4bd7fb0	documented ==-function for state colors (monochromatic)
​0f4cd95	added doctest to show behavior when states have colors
​dc5e17e	Minor correction in docstring (``...``)
​77f3804	Minor rewording in docstring
​063fb45	Merge remote-tracking branch 'aau/fsm/process-refuse-nondeterministic' (#16539) into t/16675/fsm/check_equal
​1d730fe	Merge branch 'u/cheuberg/fsm/check_equal' of trac.sagemath.org:sage into t/16674/fsm/is_monochromatic
​0f3a40e	Merge branch 'u/cheuberg/fsm/is_monochromatic' of trac.sagemath.org:sage into fsm/states_equality
​1eaa661	Merge branch 'u/cheuberg/fsm/states_equality' of trac.sagemath.org:sage (#16588) into fsm/docs-improved-new
​2d2a58d	trac #16677: include new methods and functions from new tickets
​5964e0a	trac #16677: updated list of tickets in changelog

[cheuberg]

I merged #16588 and added the functions and methods from this and preceding tickets into the TOC. Furthermore, updated list of tickets in changelog.

I have reviewed Daniel's contributions, so once you reviewed mine, please set this to positive_review.

[vbraun]

There is something wrong with

sage -t --long src/sage/doctest/sources.py
**********************************************************************
File "src/sage/doctest/sources.py", line 689, in sage.doctest.sources.FileDocTestSource._test_enough_doctests
Failed example:
    for path, dirs, files in itertools.chain(os.walk('sage'), os.walk('doc')): # long time
        path = os.path.relpath(path)
        dirs.sort(); files.sort()
        for F in files:
            _, ext = os.path.splitext(F)
            if ext in ('.py', '.pyx', '.pxi', '.sage', '.spyx', '.rst'):
                filename = os.path.join(path, F)
                FDS = FileDocTestSource(filename, DocTestDefaults(long=True,optional=True))
                FDS._test_enough_doctests(verbose=False)
Expected:
    There are 7 tests in sage/combinat/dyck_word.py that are not being run
    There are 6 tests in sage/combinat/interval_posets.py that are not being run
    There are 18 tests in sage/combinat/partition.py that are not being run
    There are 15 tests in sage/combinat/permutation.py that are not being run
    There are 14 tests in sage/combinat/skew_partition.py that are not being run
    There are 18 tests in sage/combinat/tableau.py that are not being run
    There are 8 tests in sage/combinat/crystals/tensor_product.py that are not being run
    There are 11 tests in sage/combinat/rigged_configurations/rigged_configurations.py that are not being run
    There are 15 tests in sage/combinat/root_system/cartan_type.py that are not being run
    There are 8 tests in sage/combinat/root_system/type_A.py that are not being run
    There are 8 tests in sage/combinat/root_system/type_G.py that are not being run
    There are 3 unexpected tests being run in sage/doctest/parsing.py
    There are 1 unexpected tests being run in sage/doctest/reporting.py
    There are 9 tests in sage/graphs/graph_plot.py that are not being run
    There are 3 tests in sage/rings/invariant_theory.py that are not being run
Got:
    There are 7 tests in sage/combinat/dyck_word.py that are not being run
    There are 4 tests in sage/combinat/finite_state_machine.py that are not being run
    There are 6 tests in sage/combinat/interval_posets.py that are not being run
    There are 18 tests in sage/combinat/partition.py that are not being run
    There are 15 tests in sage/combinat/permutation.py that are not being run
    There are 14 tests in sage/combinat/skew_partition.py that are not being run
    There are 18 tests in sage/combinat/tableau.py that are not being run
    There are 8 tests in sage/combinat/crystals/tensor_product.py that are not being run
    There are 11 tests in sage/combinat/rigged_configurations/rigged_configurations.py that are not being run
    There are 15 tests in sage/combinat/root_system/cartan_type.py that are not being run
    There are 8 tests in sage/combinat/root_system/type_A.py that are not being run
    There are 8 tests in sage/combinat/root_system/type_G.py that are not being run
    There are 3 unexpected tests being run in sage/doctest/parsing.py
    There are 1 unexpected tests being run in sage/doctest/reporting.py
    There are 9 tests in sage/graphs/graph_plot.py that are not being run
    There are 3 tests in sage/rings/invariant_theory.py that are not being run
**********************************************************************
1 item had failures:
   1 of   9 in sage.doctest.sources.FileDocTestSource._test_enough_doctests
    [337 tests, 1 failure, 57.03 s]

[vbraun]

Also, license for the Sage library is GPLv2+ not 3+.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​7c2ee9f

partial revert: GPL2

[dkrenn]

Replying to vbraun:

There is something wrong with

sage -t --long src/sage/doctest/sources.py
**********************************************************************
...
Expected: 
...
Got:
...
    There are 4 tests in sage/combinat/finite_state_machine.py that are not being run
...
**********************************************************************
1 item had failures:
   1 of   9 in sage.doctest.sources.FileDocTestSource._test_enough_doctests
    [337 tests, 1 failure, 57.03 s]

This was fixed by adding the line above into sources.py. Those 4 tests are indeed not tested by the doctest framework. I've created #16693 for this issue.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​21d0da6

Merge branch 't/15683/a21065ed60c9cb809181f8e8c28994e1274a8b63' into t/16677/fsm/docs-improved-new

[dkrenn]

Merged #15683 to avoid a merge conflict.

[cheuberg]

Reviewed the changes. Fater merging #15683, trac's automerge still fails for unknown reasons: merging this ticket into 6.3.beta6 does succeed.