Opened 3 years ago
Closed 3 years ago
#27917 closed defect (fixed)
Standardize doctest headers
Reported by: | gh-black-stones | Owned by: | |
---|---|---|---|
Priority: | minor | Milestone: | sage-8.9 |
Component: | documentation | Keywords: | doctest |
Cc: | jdemeyer, slelievre | Merged in: | |
Authors: | Frédéric Chapoton | Reviewers: | Kevin Lui |
Report Upstream: | N/A | Work issues: | |
Branch: | edf9e8b (Commits, GitHub, GitLab) | Commit: | edf9e8ba8ba6082330ba05b5bdd6b804d2e12925 |
Dependencies: | Stopgaps: |
Description
It has recently come to my attention that there are a few doctest strings within Sage that do not follow the standard (http://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings). Please see the comments in https://trac.sagemath.org/ticket/5548 for the details/conversation, but essentially, all doctests should be preceded by either a TESTS::
or EXAMPLES::
header.
I have found a few places where this is not done:
- set_calculus_method() of src/sage/manifolds/manifold.py
- from_tamari_sorting_tuple() of src/sage/combinat/binary_tree.py ("EXEMPLES" instead of "EXAMPLES")
- init() of GenericGraphQuery?? in src/sage/graphs/graph_database.py
- _hnf_mod() of src/sage/matrix/matrix_integer_dense.pyx
There are also a few places where we have Examples::
or Tests::
instead of EXAMPLES::
or TESTS::
, and other places have EXAMPLES:
(only one colon)... I am not sure if this matters for running doctests but for consistency, they should be fixed too.
- preimage() and dual() of src/sage/schemes/projective/projective_subscheme.py
- _richcmp_() of src/sage/schemes/projective/projective_point.py
- Lattes_map() of src/sage/schemes/projective/projective_space.py
- _call_(), SchemeMorphism_polynomial, getitem(), mul(), glue_along_domains() of src/sage/schemes/generic/morphism.py
I have undoubtedly missed many other mistakes, so I believe this ticket is two-fold - we should first compile a list of files with incorrect docstring headers, and then fix them.
Change History (8)
comment:1 follow-up: ↓ 2 Changed 3 years ago by
comment:2 in reply to: ↑ 1 Changed 3 years ago by
Replying to chapoton:
- The use of
TESTS:
andEXAMPLES:
is correct. The double colon is only needed if this is directly followed by doctests.
In more detail: if the following line is not indented, a single colon is correct, like this:
EXAMPLES: Here is some explanatory text. :: sage: 2+2 5
Using EXAMPLES::
would produce an error.
comment:3 Changed 3 years ago by
As the Sage-8.8 release milestone is pending, we should delete the sage-8.8 milestone for tickets that are not actively being worked on or that still require significant work to move forward. If you feel that this ticket should be included in the next Sage release at the soonest please set its milestone to the next release milestone (sage-8.9).
comment:4 Changed 3 years ago by
- Milestone sage-8.8 deleted
As the Sage-8.8 release milestone is pending, we should delete the sage-8.8 milestone for tickets that are not actively being worked on or that still require significant work to move forward. If you feel that this ticket should be included in the next Sage release at the soonest please set its milestone to the next release milestone (sage-8.9).
comment:5 Changed 3 years ago by
- Branch set to u/chapoton/27917
- Commit set to edf9e8ba8ba6082330ba05b5bdd6b804d2e12925
- Status changed from new to needs_review
comment:6 Changed 3 years ago by
- Status changed from needs_review to positive_review
- Type changed from PLEASE CHANGE to defect
Looks good.
I also change the ticket type to defect
.
comment:7 Changed 3 years ago by
- Milestone set to sage-8.9
- Reviewers set to Kevin Lui
comment:8 Changed 3 years ago by
- Branch changed from u/chapoton/27917 to edf9e8ba8ba6082330ba05b5bdd6b804d2e12925
- Resolution set to fixed
- Status changed from positive_review to closed
TESTS:
andEXAMPLES:
is correct. The double colon is only needed if this is directly followed by doctests.EXEMPLES
have been fixed recently.Examples
andTests
could be fixed, but this has low priority.