Opened 4 years ago

Closed 4 years ago

#10078 closed enhancement (invalid)

Change ".. warning::" to ".. WARNING::"

Reported by: jpflori Owned by: mvngu
Priority: trivial Milestone: sage-duplicate/invalid/wontfix
Component: documentation Keywords: documentation
Cc: Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

Sage coding convention encourages to use ".. WARNING::" rather than ".. warning::", however, using search_src shows the converse is done :

sage: len(search_src(".. warning::", interact=False).splitlines())
209
sage: len(search_src(".. WARNING::", interact=False).splitlines())
34

Change History (12)

comment:1 Changed 4 years ago by mvngu

  • Milestone set to sage-4.6
  • Summary changed from Change ".. warning::" to ".. WARNING::". to Change ".. warning::" to ".. WARNING::"

This situation is unfortunate. It's reminiscent of the time when many of the coding and documentation conventions were fully fleshed out or adopted. Thank you for spotting this!

It can be very invasive and time-consuming to provide a patch to fix all those files that still use ".. warning::". Such a patch would be difficult and time-consuming to review. A better approach, I think, is to pick one or two files that still use ".. warning::" and provide a patch against those files. Such a patch would be small, easy, and less time-consuming to review. Then iterate with as many tickets as possible until done.

comment:2 Changed 4 years ago by mvngu

  • Priority changed from minor to trivial

comment:3 follow-up: Changed 4 years ago by mhansen

  • Status changed from new to needs_info

Wait, why is this the case? All of the Sphinx directives are generally lower case.

comment:4 in reply to: ↑ 3 Changed 4 years ago by mvngu

Replying to mhansen:

Wait, why is this the case? All of the Sphinx directives are generally lower case.

I'm the guilty person who encourages the use of "WARNING". That's because I consider it to be a section title, just as "INPUT" is the title of the section for input, "OUTPUT" the title for the section on output, "EXAMPLES" for the title of the section on example usage, etc. I have been very careful in my use of words when I edited the documentation conventions in the Developer's Guide. I encourage the use of the upper-case form because Sphinx can parse both the lower- and upper-case versions, while refraining from saying that the upper-case version is the only acceptable usage. I'm rather ambivalent about this ticket. On the one hand, I think the upper-case form encourages consistency. On the other hand, implementing the topic of this ticket can cause some (or even a lot of) bad feeling in many people.

comment:5 follow-up: Changed 4 years ago by mhansen

The problem is that they aren't section titles, and section titles are Sphinx directives. I think that they should be separate things. The directives don't get rendered as such. One might ask, why we have EXAMPLES:: instead of ... EXAMPLES::. I think it's more clear to leave the directives as lower-cases and keep the section haedings as their own things.

comment:6 follow-up: Changed 4 years ago by jhpalmieri

First, I'm happy to leave "warning" and "note" in lowercase.

On a slightly different topic, I don't feel that strongly about it, but I actually think we should change from using INPUT and OUTPUT blocks to using the built-in Sphinx commands for this, as documented in our developer's guide. It might also not be a bad idea to add ".. examples::" and ".. tests::" directives. I'm not sure how these would work with the plain text we have interspersed with the examples, though. We could maybe add ".. references::" too, although if we can work out the details, using Sphinx's reference system might be better.

comment:7 Changed 4 years ago by jhpalmieri

I guess we could just have ".. examples::" print "EXAMPLES:", and similarly for ".. tests::" and that would be the end of it. On the other hand, if we could actually have these directives include all of the examples and interspersed text, then we could, for example, decide to omit the tests by passing a command-line option when building the docs. But I don't know how directives work well enough to know if this could be implemented in an easy-to-use way.

See the sphinx and docutils docs for information on creating directives. I haven't looked at these in any detail.

comment:8 in reply to: ↑ 5 Changed 4 years ago by mvngu

Replying to mhansen:

I think it's more clear to leave the directives as lower-cases and keep the section haedings as their own things.

I'm fine with using either the lower- or upper-case version. I see your argument about sticking to Sphinx's convention on using lower-case for directives. The relevant sections of the Developer's Guide need to be changed to mention that Sphinx's lower-case convention is preferred. And a note saying that Sphinx also accepts the upper-case version.

comment:9 in reply to: ↑ 6 Changed 4 years ago by mvngu

I think this ticket is now invalid. Agree?

comment:10 Changed 4 years ago by jhpalmieri

I agree.

comment:11 Changed 4 years ago by jason

+1 to sticking to sphinx convention.

Also, +1 to making our headings have semantic meaning (via .. constructs, or like the numpy guys do it, actually make them sphinx headings)

comment:12 Changed 4 years ago by mvngu

  • Milestone changed from sage-4.6.1 to sage-duplicate/invalid/wontfix
  • Resolution set to invalid
  • Status changed from needs_info to closed

Close as invalid.

Note: See TracTickets for help on using tickets.