Navigation

Table Of Contents

This Page

Limitations and roadmap

Integration with Sphinx

  • Sphinx integration, how to to reuse sourcecode, so the directive accepts the options ignored, cleanup option, no_check, can_abort,
  • configuration: bailout_on_abort, match=string|re|ellipsis, prompts, ignore_stderr,
  • use the Sphinx logging system which can be shut from the command line,
  • build a directive test_report inserting a table report in the doc,
  • build a directive article which takes the name of the article, and for each, creates a command runner and accumulate the cleanup code, in case of an abort.

Python/debian packaging

  • use distribute to benefit from console_script, and dependency resolution (docutils), and also because it is the new black. Maybe pip knows how to install man pages and re-hash the man-db,
  • how to package the future sphinx.ext.wordish (should the repository be on bitbucket),
  • command line argument: --help, --quiet, --prompt, --match 'exact|ellipsis|regexp', --cleanup mycleanup.sh, ignore_stderr, bailout_on_abort
  • how to use git branches to ease debian and rpm packaging? (do like the documentation on github with the gh-pages)

Interfaces

  • How to declare that a class implements a context manager, an iterable, that a member attribute is a list of certain class or a dictionary,
  • Use epydoc, or Sphinx syntax to specify the signature of methods and objects,

Tests

  • some impede readability, some are redundant, some use backdoors, some important one tests may be missing, some doctest would better be unit test and vice versa,
  • clear distinction between public (black box) and private api (white box). Proof test est the public API at least,
  • some black box testing may be needed to be launched as root and be run on every file in examples/,

objects and interfaces

  • ISessionParser

    • Universal linefeed for commands in articles written on Windows,

    • Like doctest, write hints for wordish to adjust its behavior when parsing hints in the comment after a command:

      ~$ echo boilerplate      # ignore
wildly unpredictable

~$ echo coucou >&2       # &2
coucou

~$ She is a witch        # returncode: 127
She: command not found

~$ rm -r ./temp_mount_point   # cleanup

      The returned expected could be an CommandOutput instead of simple string and carry the attribute ignore, returncode, cleanup or err.

      The idea for the cleanup command is to execute them on bailout, as they are meant to return the system in predictable state.

    • Suppress get_command() and get_output(), make turn takewhile public,

  • IReporter

    • When bailing out, it is not true that all test passed,
    • Differentiate the error (command aborted) and failure (output differs) in the report. Do not bailout on expected return value different from zero,

  • ICommandRunner

    • Make it possible to follow the session interactively (via cmds.py, GNU screen, or via tty). This means being able to read the tutorial text paragraph, then confirm next command, abort execution, take control of the shell...
    • It should be possible to put more than one ellipsis (...) per line (how does doctest do anyway?),

  • IBlockSelector

    • Execute not at parsing time but at doctree resolved time, it allows to build a data structure of articles and cleanup command instead of communicating via a flat file descriptor.

      But it is slower since wordish would be blocked until the end of parsing and resolution,

    • Support other format syntax, like markdown,

    • Support an INodeSelector( doctree_node ) -> boolean, instantiating a is_shell(), is_article(), is_cleanup(). Making it possible to gather the snippets in the following data structure:

      # essence  = [ n for n in doctree.traverse()
#             if is_article(n) or is_cleanup(n) or is_shell(n) ]
# snippets = [ split(a, is_cleanup ) for a in split( essence, is_article ) ]

Navigation

© Copyright 2010, Jean Daniel Browne. Created using Sphinx 0.6.4.