0

Re: Using sphinx-apidoc to automatically generate API reference from docstrings via the autodoc extension...

I copied the global /site-packages/sphinx/templates/apidoc/package.rst_t template to a local folder, and made a nonsense edit. When I built the API docs, the nonsense edit wasn't visible ie. the local templates didn't seem to override the global ones.

Here's my local docs/source directory:

|_ docs
   |_ source
      |_ templates
      |    package.rst_t
      |_ conf.py
      |_ index.rst

conf.py contains this directive:

templates_path = ['templates']

I built the API docs using this command:

sphinx-apidoc -e -M -f --templatedir=./templates -o ./source/autodoc ../myproject

Can anyone see what's going wrong?

James Leedham
  • 2,064
  • 1
  • 10
  • 11
  • What is your ultimate goal? It's not clear what you want to achieve. – Steve Piercy Apr 29 '20 at 12:38
  • I would like to edit the local versions of the templates so I can change the way the docstrings are displayed. So for example the global `package.rst_t` template appends "package" to the name on line 19: `{{- [pkgname, "package"] | join(" ") | e | heading }}`. I would like to remove the word "package", like this: `{{- [pkgname | e | heading }}`. – James Leedham Apr 29 '20 at 13:01
  • When you issue the command, what is the current working directory? – mzjn Apr 30 '20 at 08:51
  • 1
    Thanks @mzjn ! User error. Running from the `docs` directory, so putting `source` in the `--templatedir` path got local templates working (ie. `sphinx-apidoc -e -M -f --templatedir=./source/templates -o ./source/autodoc ../myproject`). PS. Do you happen to know if there's a way to edit templates for classes, functions etc? In `site-packages` for Sphinx there's `module.rst_t` and `package.rst_t` templates, but no equivalent (eg) `class.rst_t`..? – James Leedham Apr 30 '20 at 09:47
  • Currently there isn't a good way to do that. sphinx-apidoc generates `automodule` directives only. See also https://github.com/sphinx-doc/sphinx/issues/6788, https://github.com/sphinx-doc/sphinx/issues/2897 – mzjn Apr 30 '20 at 09:58

0 Answers0