-
Notifications
You must be signed in to change notification settings - Fork 12
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
Added support for autodoc --templatedir option #19
Conversation
README.rst
Outdated
can be found in ``site-packages/sphinx/templates/apidoc/``. This path is | ||
relative to the documentation source directory. | ||
|
||
**Optional**, defaults to ``templates``. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How does this work if a templates
directory doesn't exist. Looking at the extension source, the --templatedir
argument defaults to unset. Shouldn't we do the same?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If the templates
directory does not exist, the argument is ignored. I don't see a benefit to defaulting to unset. Considering the conf.py
generated by sphinx-quickstart
includes a definition for template_dir
(https://github.com/sphinx-doc/sphinx/blob/35965903177c6ed9a6afb62ccd33243a746a3fc0/sphinx/templates/quickstart/conf.py_t#L38), I think users are likely to expect that the same default directory will be used for apidoc templates too. This was my expectation coming in. I made this PR because I was unable to include overwrite the apidoc default templates without editing the source in my site-packages. I think defaulting to 'templates'
will save users some headaches.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we should be providing our own defaults that override the Sphinx ones...
The apidoc templates are named My motivation for defaulting to |
Adds handling for setting apidoc_template_dir in conf.py, which passes this variable along with the --templatedir command line option for sphinx-apidoc.
This enables the user to define custom templates, which is supported in sphinx.ext.apidoc but was not previously supported in sphinxcontrib/apidoc.