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:

Status badges

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: Changed 3 years ago by chapoton

  • The use of TESTS: and EXAMPLES: is correct. The double colon is only needed if this is directly followed by doctests.
  • All EXEMPLES have been fixed recently.
  • Examples and Tests could be fixed, but this has low priority.

comment:2 in reply to: ↑ 1 Changed 3 years ago by jhpalmieri

Replying to chapoton:

  • The use of TESTS: and EXAMPLES: 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 embray

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 embray

  • 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 chapoton

  • Authors set to Frédéric Chapoton
  • Branch set to u/chapoton/27917
  • Commit set to edf9e8ba8ba6082330ba05b5bdd6b804d2e12925
  • Status changed from new to needs_review

done, please review


New commits:

edf9e8bfix some Examples:: to EXAMPLES::

comment:6 Changed 3 years ago by klui

  • 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 chapoton

  • Milestone set to sage-8.9
  • Reviewers set to Kevin Lui

comment:8 Changed 3 years ago by vbraun

  • Branch changed from u/chapoton/27917 to edf9e8ba8ba6082330ba05b5bdd6b804d2e12925
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.