Opened 8 years ago
Closed 8 years ago
#16677 closed enhancement (fixed)
improve the docstrings in the finite state machines module
Reported by:  dkrenn  Owned by:  

Priority:  major  Milestone:  sage6.3 
Component:  finite state machines  Keywords:  finite_state_machine, documentation 
Cc:  cheuberg, skropf  Merged in:  
Authors:  Clemens Heuberger, Daniel Krenn  Reviewers:  Clemens Heuberger, Daniel Krenn 
Report Upstream:  N/A  Work issues:  
Branch:  21d0da6 (Commits, GitHub, GitLab)  Commit:  21d0da69e55877ef0d7ff317c6030033d07dfa1f 
Dependencies:  #16588, #15683  Stopgaps: 
Description (last modified by )
The aim of this ticket is to collect various improvements to the docstring of the finite state machines module.
Change History (16)
comment:1 Changed 8 years ago by
 Branch set to u/dkrenn/fsm/docsimprovednew
comment:2 Changed 8 years ago by
 Commit set to 7944470ff9f487929b86ac3d1d3bcffb486acf5d
 Description modified (diff)
 Reviewers set to Clemens Heuberger, Daniel Krenn
comment:3 Changed 8 years ago by
 Branch changed from u/dkrenn/fsm/docsimprovednew to u/cheuberg/fsm/docsimprovednew
comment:4 Changed 8 years ago by
 Commit changed from 7944470ff9f487929b86ac3d1d3bcffb486acf5d to 5964e0abf736c957933e511d40646ac1918a6c9e
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 remotetracking branch 'aau/fsm/processrefusenondeterministic' (#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/docsimprovednew

2d2a58d  trac #16677: include new methods and functions from new tickets

5964e0a  trac #16677: updated list of tickets in changelog

comment:5 Changed 8 years ago by
 Dependencies set to #16588
 Keywords finite_state_machine documentation added
 Status changed from new to needs_review
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.
comment:6 Changed 8 years ago by
 Status changed from needs_review to positive_review
comment:7 followup: ↓ 11 Changed 8 years ago by
 Status changed from positive_review to needs_work
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]
comment:8 Changed 8 years ago by
Also, license for the Sage library is GPLv2+ not 3+.
comment:9 Changed 8 years ago by
 Branch changed from u/cheuberg/fsm/docsimprovednew to u/dkrenn/fsm/docsimprovednew
comment:10 Changed 8 years ago by
 Commit changed from 5964e0abf736c957933e511d40646ac1918a6c9e to 7c2ee9f0605d81bf7ca86be040e4552a62cf9260
Branch pushed to git repo; I updated commit sha1. New commits:
7c2ee9f  partial revert: GPL2

comment:11 in reply to: ↑ 7 Changed 8 years ago by
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.
comment:12 Changed 8 years ago by
 Status changed from needs_work to needs_review
comment:13 Changed 8 years ago by
 Commit changed from 7c2ee9f0605d81bf7ca86be040e4552a62cf9260 to 21d0da69e55877ef0d7ff317c6030033d07dfa1f
Branch pushed to git repo; I updated commit sha1. New commits:
21d0da6  Merge branch 't/15683/a21065ed60c9cb809181f8e8c28994e1274a8b63' into t/16677/fsm/docsimprovednew

comment:14 Changed 8 years ago by
Merged #15683 to avoid a merge conflict.
comment:15 Changed 8 years ago by
 Dependencies changed from #16588 to #16588, #15683
 Status changed from needs_review to positive_review
Reviewed the changes. Fater merging #15683, trac's automerge still fails for unknown reasons: merging this ticket into 6.3.beta6 does succeed.
comment:16 Changed 8 years ago by
 Branch changed from u/dkrenn/fsm/docsimprovednew to 21d0da69e55877ef0d7ff317c6030033d07dfa1f
 Resolution set to fixed
 Status changed from positive_review to closed
Last 10 new commits:
updated AUTHORsection
statehooks explained
rewrite first few examples to avoid FSMState/FSMTransition
Corrected a few typos
finite_state_machine: added a few internal hyperlinks to documentation
FSMState: Documentation for attribute is_initial added
finite_state_machine.py: Started TOC for documentation
TOC now lists all methods and attributes
document attribute on_duplicate_transition
inserted/removed spacings and empty lines