Ticket #11615: trac_11615-document-known-bug.patch

File trac_11615-document-known-bug.patch, 2.0 KB (added by jhpalmieri, 9 years ago)

Sage library

  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User J. H. Palmieri <palmieri@math.washington.edu>
    # Date 1311188087 25200
    # Node ID 86c77c0e8088201498cd7425b789a80355e69b2b
    # Parent  51d432408f3d585567b9da965f8d1858889430dc
    #11615: sage repo: document "# optional: bug" and "# optional: requires PKG"
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b mind: 
    859859
    860860  .. note::
    861861
    862       Any text after ``optional`` is interpreted as a package name.
    863       Therefore if the doctest is marked ``optional: requires
    864       chomp``, then ``requires`` is viewed as a package
    865       name, so the test would only be run by either ``sage -t
    866       --optional f.py`` or ``sage -t
    867       --only-optional=requires,chomp f.py``.
     862      Any text after ``optional`` is interpreted as a list of package
     863      names, separated by spaces, although the words "needs" and
     864      "requires" are ignored.  Colons, periods, commas, and hyphens
     865      are also ignored, and all text is converted to lower case.
     866      Therefore if the doctest is marked ``optional: needs package
     867      CHomP``, then it would be run by ``sage -t --optional f.py`` or
     868      ``sage -t --only-optional=chomp,package f.py``.  This is
     869      probably not what was intended: the doctest should have been
     870      labeled ``optional: needs CHomP`` or just ``optional: chomp``.
     871
     872- If you are documenting a known bug in Sage, mark it as ``known bug``
     873  or ``optional: bug``.  For example::
     874
     875     The following should yield 4.  See trac ticket #2::
     876
     877        sage: 2+2 # optional: bug
     878        5
     879
     880  Then the doctest will be skipped by default, but could be revealed
     881  by running ``sage -t --only-optional=bug ...``.  (A doctest marked
     882  as ``known bug`` gets automatically converted to ``optional bug``,
     883  so it is also detected by ``--optional`` or  ``--only-optional=bug``.)
    868884
    869885-  If the entire documentation string contains all three words
    870886   ``optional``, ``package``, and ``installed``, then the entire