sage.doctest.control: Exclude doctests in files via file directives ''# sage.doctest: optional - xyz'

[mkoeppe]

When a file is marked # sage.doctest: optional - xyz, we omit it from doctesting unless --optional=xyz is given.

This will save us from having to add lots of # optional - ... tags to files in the course of modularization (#29705)

We do this by extending sage.doctest.control.skipfile, which already parses files for # nodoctest file directives.

Previous related proposals/discussions: #3260, #20427

Also related: #30746

CC: @simon-king-jena @kiwifb @roed314 @saraedum @nthiery @videlec

Component: doctest framework

Keywords: sd111

Author: Matthias Koeppe, John Palmieri

Branch/Commit: 5cc1288

Reviewer: John Palmieri, Matthias Koeppe

Issue created by migration from https://trac.sagemath.org/ticket/30778

[mkoeppe]

comment:2

Hoping we can make progress on this ticket this week - https://wiki.sagemath.org/days111

[mkoeppe]

Changed keywords from none to sd111

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,3 +1,4 @@
-When a file is marked `sage_setup: distribution = ...` (#29705), we omit it from doctesting.
+When a file is marked `sage_setup: distribution = ...` (#29705) and this distribution is not installed, we omit it from doctesting.
 
+This will save us from having to add lots of `# optional - ...` tags to files in the course of modularization (#29705)
 

[mkoeppe]

Description changed:

--- 
+++ 
@@ -2,3 +2,4 @@
 
 This will save us from having to add lots of `# optional - ...` tags to files in the course of modularization (#29705)
 
+We do this by extending `sage.doctest.control.skipfile`, which already parses files for `# nodoctest` file directives.

[mkoeppe]

comment:6

We could also parse a directive "# doctest: optional - ..." in the file header

[mkoeppe]

Branch: u/mkoeppe/sage_doctest_control__exclude_doctests_in_files_from_non_installed_distributions

[jhpalmieri]

comment:8

Replying to @mkoeppe:

We could also parse a directive "# doctest: optional - ..." in the file header

This has been discussed in the past and rejected, on the grounds that the directive is hidden when people look at the reference manual or just do x.method?, so they may expect those tests to work all the time. For any of these proposed directives, the corresponding page in the reference manual should have a clear warning. I don't know what to do about the help string for each relevant method/function/class. It's overkill to modify the help string based on such a directive, right?

[jhpalmieri]

Changed branch from u/mkoeppe/sage_doctest_control__exclude_doctests_in_files_from_non_installed_distributions to none

[jhpalmieri]

New commits:

b92e036

sage.doctest: Handle file directives '# sage.doctest: optional - xyz'

[jhpalmieri]

Branch: u/mkoeppe/sage_doctest_control__exclude_doctests_in_files_from_non_installed_distributions

[jhpalmieri]

Commit: b92e036

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,4 +1,4 @@
-When a file is marked `sage_setup: distribution = ...` (#29705) and this distribution is not installed, we omit it from doctesting.
+When a file is marked `# sage.doctest: optional - xyz`, we omit it from doctesting unless `--optional=xyz` is given.
 
 This will save us from having to add lots of `# optional - ...` tags to files in the course of modularization (#29705)
 

[mkoeppe]

Changed branch from u/mkoeppe/sage_doctest_control__exclude_doctests_in_files_from_non_installed_distributions to none

[mkoeppe]

Changed commit from b92e036 to none

[mkoeppe]

Branch: u/mkoeppe/sage_doctest_control__exclude_doctests_in_files_from_non_installed_distributions