Opened 7 years ago

Closed 7 years ago

#16677 closed enhancement (fixed)

improve the docstrings in the finite state machines module

Reported by: dkrenn Owned by:
Priority: major Milestone: sage-6.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:

Status badges

Description (last modified by dkrenn)

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 7 years ago by dkrenn

  • Branch set to u/dkrenn/fsm/docs-improved-new

comment:2 Changed 7 years ago by dkrenn

  • Authors set to Clemens Heuberger, Daniel Krenn
  • Commit set to 7944470ff9f487929b86ac3d1d3bcffb486acf5d
  • Description modified (diff)
  • Reviewers set to Clemens Heuberger, Daniel Krenn

Last 10 new commits:

adf99b3updated AUTHOR-section
511883cstate-hooks explained
f6e5189rewrite first few examples to avoid FSMState/FSMTransition
ad847f8Corrected a few typos
97fe1b6finite_state_machine: added a few internal hyperlinks to documentation
680d0a6FSMState: Documentation for attribute is_initial added
4442ce3finite_state_machine.py: Started TOC for documentation
4b66e84TOC now lists all methods and attributes
f2c3d64document attribute on_duplicate_transition
7944470inserted/removed spacings and empty lines

comment:3 Changed 7 years ago by cheuberg

  • Branch changed from u/dkrenn/fsm/docs-improved-new to u/cheuberg/fsm/docs-improved-new

comment:4 Changed 7 years ago by git

  • Commit changed from 7944470ff9f487929b86ac3d1d3bcffb486acf5d to 5964e0abf736c957933e511d40646ac1918a6c9e

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

4bd7fb0documented ==-function for state colors (monochromatic)
0f4cd95added doctest to show behavior when states have colors
dc5e17eMinor correction in docstring (``...``)
77f3804Minor rewording in docstring
063fb45Merge remote-tracking branch 'aau/fsm/process-refuse-nondeterministic' (#16539) into t/16675/fsm/check_equal
1d730feMerge branch 'u/cheuberg/fsm/check_equal' of trac.sagemath.org:sage into t/16674/fsm/is_monochromatic
0f3a40eMerge branch 'u/cheuberg/fsm/is_monochromatic' of trac.sagemath.org:sage into fsm/states_equality
1eaa661Merge branch 'u/cheuberg/fsm/states_equality' of trac.sagemath.org:sage (#16588) into fsm/docs-improved-new
2d2a58dtrac #16677: include new methods and functions from new tickets
5964e0atrac #16677: updated list of tickets in changelog

comment:5 Changed 7 years ago by cheuberg

  • 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 7 years ago by dkrenn

  • Status changed from needs_review to positive_review

comment:7 follow-up: Changed 7 years ago by vbraun

  • 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 7 years ago by vbraun

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

comment:9 Changed 7 years ago by dkrenn

  • Branch changed from u/cheuberg/fsm/docs-improved-new to u/dkrenn/fsm/docs-improved-new

comment:10 Changed 7 years ago by git

  • Commit changed from 5964e0abf736c957933e511d40646ac1918a6c9e to 7c2ee9f0605d81bf7ca86be040e4552a62cf9260

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

7c2ee9fpartial revert: GPL2

comment:11 in reply to: ↑ 7 Changed 7 years ago by 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.

comment:12 Changed 7 years ago by dkrenn

  • Status changed from needs_work to needs_review

comment:13 Changed 7 years ago by git

  • Commit changed from 7c2ee9f0605d81bf7ca86be040e4552a62cf9260 to 21d0da69e55877ef0d7ff317c6030033d07dfa1f

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

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

comment:14 Changed 7 years ago by dkrenn

Merged #15683 to avoid a merge conflict.

comment:15 Changed 7 years ago by cheuberg

  • 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 7 years ago by vbraun

  • Branch changed from u/dkrenn/fsm/docs-improved-new to 21d0da69e55877ef0d7ff317c6030033d07dfa1f
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.