How about moving the AUTHORS section to the last?

[Kwankyu Lee]

Hi all,

In the ticket  

https://trac.sagemath.org/ticket/22847

I introduced a change that could be controversial. I propose to move the AUTHORS section to the last of the heading:

r"""
<Very short 1-line summary>

<Paragraph description>

EXAMPLES::

<Lots and lots of examples>

AUTHORS:

- YOUR NAME (2005-01-03): initial version

- person (date in ISO year-month-day format): short desc

"""

As far as I know, some authors already follow this style in practice but I think this should be official. So I seek your consensus.

[Jori Mantysalo]

On Thu, 20 Apr 2017, Kwankyu Lee wrote:

> I propose to move the AUTHORS section to the last of the heading:

+1.

--
Jori Mäntysalo

[Simon King]

On 2017-04-21, Jori Mantysalo <Jori.Ma...@uta.fi> wrote:
> On Thu, 20 Apr 2017, Kwankyu Lee wrote:
>
>> I propose to move the AUTHORS section to the last of the heading:
>
> +1.

Question: Do you suggest to *manually* move the AUTHORS: section of
*all* affected docstrings? Or do you merely suggest to modify Sage's
doc builder, so that it will always create an autput where the
AUTHORS: section comes last -- without the need to change the doc
strings?

Best regards,
Simon

[Jori Mäntysalo]

The ticket suggested by Lee, #22847, contains only modification to
the developer manual.

Having more structured docstring would of course be a good thing. Then we
could, as an example, hide the AUTHORS-section if wanted etc.

--
Jori Mäntysalo

[Kwankyu Lee]

> Question: Do you suggest to *manually* move the AUTHORS: section of
> *all* affected docstrings? Or do you merely suggest to modify Sage's
> doc builder

I merely suggest the official location of the AUTHORS section, as done in the ticket.

 

Having more structured docstring would of course be a good thing. Then we
could, as an example, hide the AUTHORS-section if wanted etc. 

Or put it all the way back to the end of the html page, behind the list of classes and methods :-)

Besides I want to put a separator just before the list of classes and methods.

But making all these things automatic requires Sphinx wizardry, which is out of my ability. Sigh...

 

[Kwankyu Lee]

Hi,

No one objected to this proposal by now, and one person is positively for it. Then would someone review the ticket:

https://trac.sagemath.org/ticket/22847

This would be a very easy review.

Kwankyu