Skip to content
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

Merged
merged 6 commits into from
Jan 16, 2024

Conversation

itsmoosh
Copy link
Contributor

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.

@itsmoosh itsmoosh marked this pull request as draft November 16, 2023 00:38
@itsmoosh itsmoosh marked this pull request as ready for review November 16, 2023 00:55
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``.
Copy link
Member

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?

Copy link
Contributor Author

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.

Copy link
Member

@stephenfin stephenfin left a 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...

@itsmoosh
Copy link
Contributor Author

itsmoosh commented Nov 22, 2023

I don't think we should be providing our own defaults that override the Sphinx ones...

The apidoc templates are named module.rst_t, package.rst_t, and toc.rst_t. None of the Sphinx templates have these names, so we are not providing any defaults that override any others.

My motivation for defaulting to 'templates' is about providing expected behavior for users. Including this as the default will not create any conflicts, because the directory is neither created nor populated by default. The user must place templates in this directory in order to overwrite the defaults, so if they have done so they have already intended to alter the default behavior.

@itsmoosh itsmoosh requested a review from stephenfin November 22, 2023 22:41
@stephenfin stephenfin merged commit 8be157f into sphinx-contrib:master Jan 16, 2024
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants