apidoc: Move apidoc to ext/apidoc #3929
Conversation
stephenfin
force-pushed
the
move-sphinx-apidoc-to-ext
branch
from
7ddda19 to
dd8508d
Compare
sphinx/ext/apidoc.py
Outdated
| @@ -0,0 +1,439 @@ | |||
| # -*- coding: utf-8 -*- | |||
| """ | |||
| sphinx.apidoc | |||
There was a problem hiding this comment.
This should be sphinx.ext.apidoc.
| @@ -0,0 +1,439 @@ | |||
| # -*- coding: utf-8 -*- | |||
There was a problem hiding this comment.
It seems this is a new file.
Please rename from sphinx/apidoc.py and create sphinx/apidoc.py as a new file to keep commit history,
There was a problem hiding this comment.
I'm not able to do anything about this. Git does file rename detection automatically (git [mv] might well be an alias for git cp [src] [dst] and git rm [src]), and its heuristics seem to be failing us here.
|
It seems travis raises errors. please check them. @shimizukawa Do you have any comments? |
|
I have no objection. |
|
Thanks, either is okay. I think |
stephenfin
force-pushed
the
move-sphinx-apidoc-to-ext
branch
from
dd8508d to
86d24ed
Compare
|
@tk0miya OK, I've pushed the reworked version up and the build looks to be good now (it was a pep8 issue). Think that's all that's needed now? |
It is and it isn't 😄 The In the long term, I'd really like to see all three packages moved out of the Sphinx core and into their own package(s) in the sphinx-doc namespace, for all the reasons given in the commit message. I think a separate package would be a better way of indicating that this is very much an add-on to Sphinx, rather than a key, core piece of functionality. However, I'm not in the position to make this call myself nor would I be confident enough with the source (yet!) to maintain this new package myself. I'll wait til I've more work done with the Sphinx codebase before committing myself here, heh. |
stephenfin
force-pushed
the
move-sphinx-apidoc-to-ext
branch
2 times, most recently
from
2766394 to
aa45fad
Compare
|
Could I get some eyes on this again? I think I've resolved everything that needs resolving? |
The 'sphinx-apidoc' tool is no longer the only kid on the block when it comes to automatic documentation of Python projects, with the likes of 'sphinx-autoapi' in development [1], and is not really maintained. Given the fact that the tool is tangential to Sphinx's main goal, there isn't really anything that warrants its continue existence as a core module. Signify this by moving the feature to 'ext'. This allows the feature to continue to exist in the package, but indicates that stability might be worse than one would expect from the core library. To avoid breaking packages that are using this feature directly, such as pbr [3], aliases for the old 'main' method are included. This is based on what Django does and, like Django, will allow us to safely remove the old modules in Sphinx 2.0. [1] https://github.com/rtfd/sphinx-autoapi [2] sphinx-doc#3485 (comment) [3] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695 Signed-off-by: Stephen Finucane <stephen@that.guru>
stephenfin
force-pushed
the
move-sphinx-apidoc-to-ext
branch
from
aa45fad to
96cf498
Compare
|
Merged. Thank you for your good work! |
The 'sphinx-apidoc' tool is no longer the only kid on the block when it
comes to automatic documentation of Python projects, with the likes of
'sphinx-autoapi' in development [1] and is not really maintained. Given
the fact that the tool is tangential to Sphinx's main goal, there isn't
really anything that warrants its continue existence as a core module.
Signify this by moving the feature to 'ext'. This allows the feature to
continue to exist in the package, but indicates that stability might be
worse than one would expect from the core library.
To avoid breaking packages that are using this feature directly, such as
pbr [3], aliases for the old 'main' method are included. This is based
on what Django does and, like Django, will allow us to safely remove the
old modules in Sphinx 2.0.
[1] https://github.com/rtfd/sphinx-autoapi
[2] #3485 (comment)
[3] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695