Automatize ..autosummary:: of a module

[jowezarek]

I am working on a documentation for a Python library for isogeometric analysis.
My team decided to use Sphinx and was very pleased with the initial draft, but soon we noticed that maintaining the documentation is more tedious than expected.

In particular, hard coding all method and class names of a module for the ..autosummary:: directive quickly causes problems if one is not careful.

An example .rst file of one of the submodules looks like this:

module.submodule
================

.. automodule:: package.module.submodule

.. rubric:: Overview

.. currentmodule:: package.module.submodule
.. autosummary::
   method1
   method2
   class1
   class2
   class3

.. rubric:: Class inheritance

.. inheritance-diagram:: package.module.submodule

.. rubric:: Details

.. automodule:: package.module.submodule
   :members:
   :undoc-members:
   :exclude-members:
   :show-inheritance:

The initial .. automodule:: directive includes the docstring of the submodule at the top of the page.
The following .. autosummary:: directive includes a list of all methods and classes declared in the submodule.
.. inhertiance-diagram:: includes an inheritance diagram. (of course)
And finally, unfortunately including a duplicate module docstring, we included a detailed list of everything inside the module using .. automodule:: once again.

The issue is that we have to explicitly mention all method and class names in the .. autosummary:: part. A :members: option, compare with .. automodule::, does not exist.

Is there a way to automatize this process that I have overlooked while browsing stackoverflow?

[electric-coder]

@jowezarek I don't think this is a proper post for discussions because there's nothing here to discuss, this is a usage question. It should be closed and deleted to keep the discussions tab on-topic.

Please notice that Sphinx's GitHub issues are dedicated to reporting bugs and posting feature requests. If you have a usage question and need help such questions should be asked at Stack Overflow using the python-sphinx tag.

---

Stack Overflow questions have a Minimal, Reproducible Example requirement (on GitHub this is also generally considered an essential feature), in your case the question has several problems:

1. You're asking about more than 1 directive at the same time. (Question isn't focused.)
2. The .. rubric:: is unnecessary to the example. (Example is not minimal.)
3. You don't include an example of the default autodoc settings in conf.py. (Example is not reproducible.)
4. The .. inhertiance-diagram:: is orthogonal to the main question. (Example is not minimal.)
5. Lacks the Python input. (Example is not reproducible.)
6. Lacks the HTML output. (Generally desirable for easier visual inspection of the problem.)

[picnixz]

Actually, it does fall into the category of Q/A. The purpose of the discussion was to let people ask questions here instead of SO where only the community would ask for help.

People used to open issues with questions but we told them to ask it on SO because issues were not meant for that. However, discussions are meant for this (if they don't want to ask the question on SO). It's just that asking on both sides may help them getting an answer earlier (I personally don't look at SO questions).

---

Now, for you question,

I actually never used autosummary itself because I only use autodoc. However, I think you could generate directly the whole documentation without bothering to hard-code methods. And you could also change how it is rendered using templates. I think this post could help you: https://stackoverflow.com/questions/48074094/use-sphinx-autosummary-recursively-to-generate-api-documentation

I'm only passing today so note that maintainers may not reply to Q/A that are not related to core topics.

[electric-coder]

However, discussions are meant for this

@picnixz it's clear to me you haven't put enough thought into this. Almost since Sphinx exists usage Q&A has been directed to Stack Overflow - it's a long standing tradition that has served Python/Sphinx well.

In fact if I remember correctly @AA-Turner wisely stated he hoped the discussion tab wouldn't start attracting usage Q&A. This has been stated policy for a decade, and I think it's the only correct choice. The reasons for this shouldn't even need be enumerated, but for the sake of discussion:

1. On SO the community at large can edit and curate Q&A, that's not possible on GitHub and thus you're bottle-necking any necessary Q&A maintenance to a tiny group of repository curators whose main focus is development. Maintaining the 3,723 Sphinx questions on SO (I can inquire how many question were deleted and aren't visible) is a lot of work that took hundreds of users, and you're reinventing the wheel by proposing to allow usage questions here that will mostly be a duplication.

2. On SO you get an entire system (and accompanying policies) that's mature and geared towards Q&A. GitHub just can't compare in service quality in any of those dimensions. (Communities that keep their own usage Q&A on average have a Q&A of inferior quality.)

3. The "community" and the Q&A repository is at SO, that's a long standing Sphinx/Python tradition on a scope that transcends Sphinx alone. (What to do when questions that are Sphinx+Anything-Else start being asked here, and the repository doesn't have enough resident experts in the "everything-else" technology?)

4. By allowing Q&A on discussions you'll be diluting the tab's focus and the community won't be served well. Just the fact that "duplication" is introduced will require of developers to research in both repositories for usage questions, so that alone just created an additional problem instead of a solution.

[picnixz]

Well.. in the announcement, it's said it's for "asking". For me it means also "well.. if there are questions, we can always reply if we have time".

Though, maybe we should clarify what falls into 'basic' questions then. But yeah, maybe for this specific question, SO would have been better. But if it's something that only some people know (like latex black magic), this may go here.

[jayaddison]

I've recently migrated a couple of items from the GitHub issues tracker to this discussions area because I didn't feel that they were bugs, but I wasn't aware of the policy of preferring to redirect to StackOverflow.

I don't think we should duplicate Q&A areas, and I agree that there's a lot of value in the conversations and answers on StackOverflow so far. In future I'll tend towards closing-out question-like issues and recommending StackOverflow for them instead.

[picnixz]

Fine, let's do this:

• If the issue/discussion is too high-level, we redirect it to SO.
• If the issue is low-level and probably won't get an answer on SO, we make it a discussion.
• If it's a real issue, we keep it as is.

Since we are going off-topic for this discussion, I'm closing it (I don't think I have anything to say for this discussion since it can be solved with past SO posts).