Eliminate use of __init__.py files for supplying package docstrings

[mkoeppe]

... as in src/sage/categories/__init__.py or src/sage/combinat/__init__.py

(part of #32501)

CC: @tscrim @kwankyu @nthiery

Component: refactoring

Author: Kwankyu Lee

Branch: ee4367d

Reviewer: Matthias Koeppe

Issue created by migration from https://trac.sagemath.org/ticket/32508

[kwankyu]

Branch: u/klee/32508

[kwankyu]

Author: Kwankyu Lee

[sagetrac-git]

Commit: 5dcb3f5

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

5dcb3f5

Remove docstrings from __init__.py

[kwankyu]

comment:4

Previously

sage: import sage.combinat
sage: sage.combinat.quickref?

worked. Not anymore with the patch. We should

sage: import sage.combinat.quickref
sage: sage.combinat.quickref?

The same with sage.combinat.tutorial

[kwankyu]

comment:5

More seriously, before the patch,

sage: import sage.combinat
sage: help(sage.combinat)

gives a nice ... help. Could we retain this functionality somehow while eliminating the content of sage.combinat.__init__.py?

[mkoeppe]

comment:6

I guess with a bit of extra code in src/sage/misc/sagedoc.py, where help is defined, we could do this

[kwankyu]

comment:7

Replying to @mkoeppe:

I guess with a bit of extra code in src/sage/misc/sagedoc.py, where help is defined, we could do this

I cannot guess how. Where should the content go? Do you imagine a file like src/sage/combinat/doc.rst or something?

[kwankyu]

comment:8

src/sage/combinat/__doc__.py would be better name for that.

[mkoeppe]

comment:9

+1 on __doc__.

[kwankyu]

comment:10

Replying to @mkoeppe:

+1 on __doc__.

Do you mean __doc__ without .py extension?

[mkoeppe]

comment:11

With .py, like you suggested

[kwankyu]

comment:12

Then __doc__.py with a python docstring ("""...""")?

[kwankyu]

comment:13

On the other hand, I wonder if there is a solution(or recommendation) for this problem(package docstring) in python level as this seems a general issue with namespace packages.

[mkoeppe]

comment:14

Replying to @kwankyu:

Then __doc__.py with a python docstring ("""...""")?

Yes, that's what I thought