search

readthedocs / sphinx-autoapi

A new approach to API documentation in Sphinx.
https://sphinx-autoapi.readthedocs.io/
MIT License
415 stars 126 forks source link

Using original module.rst as custom template throws errors #415

Closed f-fuchs closed 6 months ago

f-fuchs commented 6 months ago

Hey,

I wanted to modify the module.rst so that autosummary directive uses the :nosignature: option, but when I just copy the module.rst from github or from my local environment the sphinx build command already throws errors.

I checked the encoding and both files are saved as UTF-8 and when I downloaded from github I used this link https://github.com/readthedocs/sphinx-autoapi/blob/main/autoapi/templates/python/module.rst?plain=1 and used the download as raw option.

C:\Users\f.fuchs\Desktop\Git\simcats\docs\source\_templates/python/module.rst:8: ERROR: Error in "py:module" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. py:module:: {{ obj.name }}
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:23: ERROR: Unexpected indentation.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:28: WARNING: Definition list ends without a blank line; unexpected unindent.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:39: ERROR: Unexpected indentation.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:44: WARNING: Definition list ends without a blank line; unexpected unindent.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:74: WARNING: Definition list ends without a blank line; unexpected unindent.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:90: WARNING: Definition list ends without a blank line; unexpected unindent.
C:\Users\f.fuchs\Desktop\Git\project\docs\source\_templates/python/module.rst:105: WARNING: Definition list ends without a blank line; unexpected unindent.
f-fuchs commented 6 months ago

Okay the solution is adding templates_path = ['_templates'] to conf.py as described in this issue https://github.com/readthedocs/sphinx-autoapi/issues/198#issuecomment-620745004. Maybe this can be added to the offical documentation https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-customise-layout-through-templates aswell.