Integrate the 'sphinx-apidoc' command in the setuptools command

[stephenfin]

Subject: Integrate the sphinx-apidoc command in the setuptools command

Feature or Bugfix

• Feature

Purpose

• Integrate the sphinx-apidoc command in the setuptools command

Detail

Allow running of the 'apidoc' command before building documentation.
This necessitates three new configuration options:

• 'apidoc'
• 'apidoc-dir'
• 'apidoc-exclude'

These are all documented. Anyone wanting more configurability should
continue running the 'sphinx-apidoc' command separately

Relates

• #1135

[tk0miya]

Is there any advantage to integration? I think autosummary is better for such case.

@shimizukawa do you have opinion for this?

[tk0miya]

Is there any advantage to integration? I think autosummary is better for such case.

@shimizukawa do you have opinion for this?

[shimizukawa]

+1 to tk0miya.
Additionally, document uploading to PyPI (pythonhosted) has been deprecated, so I think adding a new document-related command to setup.py now is not a good idea.

refs: https://mail.python.org/pipermail/distutils-sig/2016-October/029727.html

[shimizukawa]

+1 to tk0miya.
Additionally, document uploading to PyPI (pythonhosted) has been deprecated, so I think adding a new document-related command to setup.py now is not a good idea.

refs: https://mail.python.org/pipermail/distutils-sig/2016-October/029727.html

[stephenfin]

@tk0miya I'm not aware of the differences between apidoc and autosummary. Could you elaborate? Fwiw, I'm hoping to integrate the functionality that pbr provides in their build_sphinx subclass.

@shimizukawa Does this affect the build_sphinx target also or just the upload_sphinx one? I've no intention of modifying the latter.

[stephenfin]

@tk0miya I'm not aware of the differences between apidoc and autosummary. Could you elaborate? Fwiw, I'm hoping to integrate the functionality that pbr provides in their build_sphinx subclass.

@shimizukawa Does this affect the build_sphinx target also or just the upload_sphinx one? I've no intention of modifying the latter.

[tk0miya]

With my very less knowledge about auto* extensions, autosummary with autosummary_generate option works same as sphinx-apidoc command.
@shimizukawa is my understanding wrong?

BTW, I could not review and maintain them because I'm not good at autodoc, autosummary and apidoc modules.
So if you want integrate pbr with Sphinx, I need someone become the maintainer of these modules.

[tk0miya]

With my very less knowledge about auto* extensions, autosummary with autosummary_generate option works same as sphinx-apidoc command.
@shimizukawa is my understanding wrong?

BTW, I could not review and maintain them because I'm not good at autodoc, autosummary and apidoc modules.
So if you want integrate pbr with Sphinx, I need someone become the maintainer of these modules.

[shimizukawa]

Does this affect the build_sphinx target also or just the upload_sphinx one?

@stephenfin build_sphinx is not affected by the deprecation of upload_sphinx. I was thinking that the two were indivisible, because I thought that build_sphinx is necessary to upload_sphinx with setup.py command.

@tk0miya command name of autosummary is sphinx-autogen, so sphinx-apidoc is not be able to replace with autosummary_generate feature.

[shimizukawa]

Does this affect the build_sphinx target also or just the upload_sphinx one?

@stephenfin build_sphinx is not affected by the deprecation of upload_sphinx. I was thinking that the two were indivisible, because I thought that build_sphinx is necessary to upload_sphinx with setup.py command.

@tk0miya command name of autosummary is sphinx-autogen, so sphinx-apidoc is not be able to replace with autosummary_generate feature.

[stephenfin]

@tk0miya command name of autosummary is sphinx-autogen, so sphinx-apidoc is not be able to replace with autosummary_generate feature.

@shimizukawa So they're different features, right? Have I taken the correct approach here?

BTW, I could not review and maintain them because I'm not good at autodoc, autosummary and apidoc modules.
So if you want integrate pbr with Sphinx, I need someone become the maintainer of these modules.

@tk0miya I'm afraid I'm in the same boat. Who is the maintainer of these, if anyone?

[stephenfin]

@tk0miya command name of autosummary is sphinx-autogen, so sphinx-apidoc is not be able to replace with autosummary_generate feature.

@shimizukawa So they're different features, right? Have I taken the correct approach here?

BTW, I could not review and maintain them because I'm not good at autodoc, autosummary and apidoc modules.
So if you want integrate pbr with Sphinx, I need someone become the maintainer of these modules.

@tk0miya I'm afraid I'm in the same boat. Who is the maintainer of these, if anyone?

[tk0miya]

I'm afraid I'm in the same boat. Who is the maintainer of these, if anyone?

TBH, there are no active maintainers for them.
I feel Sphinx is too large to maintenance in few members. So I'd like to keep sphinx-core simple.
(Especially, autodoc and autosummary are very complicated to understand its design...)

[tk0miya]

I'm afraid I'm in the same boat. Who is the maintainer of these, if anyone?

TBH, there are no active maintainers for them.
I feel Sphinx is too large to maintenance in few members. So I'd like to keep sphinx-core simple.
(Especially, autodoc and autosummary are very complicated to understand its design...)