Sphinx directives in upper case?

[Kwankyu Lee]

Hi,

Our developer guide dictates to write Sphinx directives in upper case. So for example, ".. MATH::" instead of ".. math::". By the way, it seems that Sphinx community seems to regard lower case as norm. So my question is: why do we insist upper case? Could anyone point to a discussion thread that decided on this?

Thanks in advance. 

[Kwankyu Lee]

In my humble opinion,  except 

".. SEEALSO::", "..WARNING::", ".. TODO::", ".. NOTE::", ".. RUBRIC::", ".. PLOT::", "..TOPIC::", which seek for reader's attention, 

we should use lower case (by default) for all other directives, following Sphinx community's trend. In particular, ".. MATH::" is only distracting.

[TB]

On 25/01/2024 7:06, Kwankyu Lee wrote:

Hi,

Our developer guide dictates to write Sphinx directives in upper case. So for example, ".. MATH::" instead of ".. math::". By the way, it seems that Sphinx community seems to regard lower case as norm. So my question is: why do we insist upper case? Could anyone point to a discussion thread that decided on this?

More than 13 years ago we have https://github.com/sagemath/sage/issues/10077 and https://github.com/sagemath/sage/issues/10078 that have comments about the case. Some further history might stem from stropping... For those looking in the docs, one place is here.

No strong opinion from me, except maybe for having consistency within a given file. The INPUT and OUTPUT blocks are related, but they are not directives. Do you think they should be?

Regards,

TB

[Travis Scrimshaw]

I think it is more confusing to mix the two. I vote for keeping everything all uppercase since everything else that is analogous uses all uppercase letters.

Best,
Travis

[Kwankyu Lee]

I was going to suggest to use uppercase only for header-like directives, excluding thereby ".. math::" in particular.

but as Travis expressed, it would be confusing to change a long-held tradition, unless there is unanimous agreement. 

So I will stop here. Thanks for the info and opinions.

[Kwankyu Lee]

More than 13 years ago we have https://github.com/sagemath/sage/issues/10077 and https://github.com/sagemath/sage/issues/10078 that have comments about the case. Some further history might stem from stropping...

Thanks for the pointers. The term "stropping" is new to me :-)

 

For those looking in the docs, one place is here.

Yes. That is the origin of my suggestion.

 

No strong opinion from me, except maybe for having consistency within a given file. The INPUT and OUTPUT blocks are related, but they are not directives. Do you think they should be?

I don't want to suggest changes from established styles. Currently the sage reference manual is following the rules set in the sage developer guide. Other files follow the Sphinx standard. I agree with "consistency within a given file".