-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Subpackage not in toc #4520
Comments
Is this related with #4449? If true, it was already fixed at HEAD of stable branch. |
Ah, sorry. it is not related with this.
|
With #4334, apidoc certainly ignores Note: #4449 fixed the problem if |
@tk0miya this is still a major bug and effects all packages that implement django commands, as they are in |
The reverting causes broken toctree again (see #4334). So only my concern is what document should be generated for |
I would simply not omit empty packages. I would add them. So yes, empty file with a title. |
I'd not made a empty package ever, so I don't have strong opinion for this. @zufallsgenerator what do you think? |
I'd say in that case, keep it as it is.
…On 16 Feb 2018 12:43, "Takeshi KOMIYA" ***@***.***> wrote:
I'd not made a empty package ever, so I don't have strong opinion for this.
I feel both skipping the package and creating empty page are natural. So
either behavior is fine to me.
@zufallsgenerator <https://github.com/zufallsgenerator> what do you think?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#4520 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AC-TQOvN0KqCfE2lvC2GZgkyZw3tkCpGks5tVWnLgaJpZM4Rw0GL>
.
|
I guess you mean we should keep the behavior. Ok, that means we omit empty packages but do not consider a package empty if it does have a sub-package underneath. |
Sorry, I answered on the go (through an e-mail) and didn't get read the entire context. I now understand @codingjoe 's concern about the django commands that are in subfolders. I think the entire reason why this is so hard to reason about, is the conditions that says that files that contain less or equal than 2 bytes should be skipped. Removing this check removes the need for a lot of special cases and fixes like mine (#4334). The need to call So, just skipping the https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/apidoc.py#L198 and it would solve this issue. And an addition, the exact example put forth in this bug will render an inconsistent TOC in 1.6.5, I think @codingjoe meant to add something like this too for the django commands example:
|
True, this is a more realistic example to reproduce the problem. pip install django
django-admin startproject example .
mkdir -p example/management/commands
touch example/management/__init__.py
touch example/management/commands/__init__.py
echo '"""Docstring"""' > example/management/commands/my_customer_command.py |
Ok, I will open a PR about it. I don't know if I can finish it today, but I'll try to get it done EOW. |
I am working on a fix. Will push today. |
…kipping folders with only an empty __init__.py has been removed. The reason for this is that it was never working consistently in the first place and made the code unnecessary hard to reason about. Tests for the TOC generation have been added, as well as tests for the exclude mechanism since they are coupled. One test (test_ext_apidoc.py::test_exclude) has also been modified to reflect the new behaviour.
(Pull request)(#4670) added, should probably go to master and then 1.7.1 |
@tk0miya can we move this ahead? I am starting to freeze sphinx to 1.6.5 in more and more of my packages because people complain about missing documentation. |
…kipping folders with only an empty __init__.py has been removed. The reason for this is that it was never working consistently in the first place and made the code unnecessary hard to reason about. Tests for the TOC generation have been added, as well as tests for the exclude mechanism since they are coupled. One test (test_ext_apidoc.py::test_exclude) has also been modified to reflect the new behaviour.
Subject: Subpackage not in toc
Problem
In this commit it seems, there was a bug introduce. The bug does is the reverse of what the commit is trying to achieve.
Subpackages in version
Sphinx (sphinx-apidoc) 1.6.6
are only picked up if they DO NOT contain a__init__.py
file. Which doesn't make them packages but folder.Procedure to reproduce the problem
Environment info
The text was updated successfully, but these errors were encountered: