Sage Developer's Guide - Mirrors

Sage Developer’s Guide, Release 6.1.1Using search_src from the Sage prompt (or grep), one can easily find the aforementioned keywords. In the caseof todo: not implemented, one can use the results of such a search to direct further development on Sage.4.1.6 Running Automated TestsThis section describes Sage’s automated testing of test files of the following types: .py, .pyx, .sage, .rst.Briefly, use sage -t to test that the examples in behave exactly as claimed. See the followingsubsections for more details. See also Documentation Strings for a discussion on how to include examples in documentationstrings and what conventions to follow. The chapter Doctesting the Sage Library contains a tutorial ondoctesting modules in the Sage library.Testing .py, .pyx and .sage FilesRun sage -t to test all code examples in filename.py. Similar remarks apply to .sageand .pyx files:sage -t [--verbose] [--optional] [files and directories ... ]The Sage doctesting framework is based on the standard Python doctest module, but with many additional features(such as parallel testing, timeouts, optional tests). The Sage doctester recognizes sage: prompts as well as >>>prompts. It also preparses the doctests, just like in interactive Sage sessions.Your file passes the tests if the code in it will run when entered at the sage: prompt with no extra imports. Thususers are guaranteed to be able to exactly copy code out of the examples you write for the documentation and havethem work.For more information, see Doctesting the Sage Library.Testing ReST DocumentationRun sage -t to test the examples in verbatim environments in ReST documentation.Of course in ReST files, one often inserts explanatory texts between different verbatim environments. To link togetherverbatim environments, use the .. link comment. For example:EXAMPLES::sage: a = 1Next we add 1 to ‘‘a‘‘... link::sage: 1 + a2If you want to link all the verbatim environments together, you can put .. linkall anywhere inthe file, on a line by itself. (For clarity, it might be best to put it near the top of the file.)Then sage -t will act as if there were a .. link before each verbatim environment. The fileSAGE_ROOT/devel/sage/doc/en/tutorial/interfaces.rst contains a .. linkall directive, forexample.You can also put .. skip right before a verbatim environment to have that example skipped when testing the file.This goes in the same place as the .. link in the previous example.4.1. General Conventions 31