how to customize sphinx.ext.autosummary rst template?

  • Last Update :
  • Techknowledgy :

Use the :template: option:

..autosummary::
   : template: mytemplate.rst

Suggestion : 2

You can specify a custom template with the template option. For example, .. autosummary:: :template: mytemplate.rst sphinx.environment.BuildEnvironment would use the template mytemplate.rst in your templates_path to generate the pages for all entries listed. See Customizing templates below. New in version 1.0. ,You can specify a custom template with the template option. For example,,You can specify the recursive option to generate documents for modules and sub-packages recursively. It defaults to disabled. For example, .. autosummary:: :recursive: sphinx.environment.BuildEnvironment New in version 3.1. ,If you don’t want the autosummary to show function signatures in the listing, include the nosignatures option: .. autosummary:: :nosignatures: sphinx.environment.BuildEnvironment sphinx.util.relative_uri

..currentmodule::sphinx

   ..autosummary::

   environment.BuildEnvironment
util.relative_uri
..autosummary::
   : toctree: DIRNAME

sphinx.environment.BuildEnvironment
sphinx.util.relative_uri
..autosummary::
   : nosignatures:

   sphinx.environment.BuildEnvironment
sphinx.util.relative_uri
..autosummary::
   : template: mytemplate.rst

sphinx.environment.BuildEnvironment
..autosummary::
   : recursive:

   sphinx.environment.BuildEnvironment
$ sphinx - autogen - o generated * .rst

Suggestion : 3

site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst (additional lines noted on right):,Is your feature request related to a problem? Please describe. The new :recursive: option for sphinx.ext.autosummary is great. I can point Sphinx at the top of my package and have it find every module, however deeply nested. For each module it creates neat summary tables listing all the attributes, classes, exceptions and functions in those modules. This is all fantastic.,Basically, the solution involves adding a :toctree: option to every .. autosummary:: directive in the default module.rst template so that documentation pages get generated for attributes, classes, exceptions and functions out-of-the-box, like this:,This prevents the auto summaries for the classes, functions and methods of the package.submodule.subsubmodule.subsubsubmodule from being generated and showing up using the :recursive: option. I still have to add the following code to make them show up manually:

site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst (additional lines noted on right):

{
   {
      fullname | escape | underline
   }
}

..automodule::{
   {
      fullname
   }
}

{
   % block attributes %
} {
   %
   if attributes %
}..rubric::Module Attributes

   ..autosummary::
   : toctree: < --add this line {
      %
      for item in attributes %
   } {
      {
         item
      }
   } {
      % -endfor %
   } {
      % endif %
   } {
      % endblock %
   }

{
   % block functions %
} {
   %
   if functions %
}..rubric::{
      {
         _('Functions')
      }
   }

   ..autosummary::
   : toctree: < --add this line {
      %
      for item in functions %
   } {
      {
         item
      }
   } {
      % -endfor %
   } {
      % endif %
   } {
      % endblock %
   }

{
   % block classes %
} {
   %
   if classes %
}..rubric::{
      {
         _('Classes')
      }
   }

   ..autosummary::
   : toctree: < --add this line {
      %
      for item in classes %
   } {
      {
         item
      }
   } {
      % -endfor %
   } {
      % endif %
   } {
      % endblock %
   }

{
   % block exceptions %
} {
   %
   if exceptions %
}..rubric::{
      {
         _('Exceptions')
      }
   }

   ..autosummary::
   : toctree: < --add this line {
      %
      for item in exceptions %
   } {
      {
         item
      }
   } {
      % -endfor %
   } {
      % endif %
   } {
      % endblock %
   }

{
   % block modules %
} {
   %
   if modules %
}..rubric::Modules

   ..autosummary::
   : toctree:
   : recursive: {
      %
      for item in modules %
   } {
      {
         item
      }
   } {
      % -endfor %
   } {
      % endif %
   } {
      % endblock %
   }

I am working with it where I have a following folder structure:-

.├──README.md├── __init__.py├── docs│├── Makefile│├── make.bat│└── source│├── _autosummary││├──...│├──_templates││├── custom - class - template.rst││└── custom - module - template.rst│├── conf.py│└── index.rst├── extract│├── README.md│├── __init__.py│├── folder_1││├── a.py││├── __init__.py││├── b.py││├── c.py│├── folders_2││├── __init__.py││├── d.py││└── e.py│├── folder_3││├── __init__.py││├── f.py└── transform├── __init__.py├── g.py└── h.py

The script for templates is completely same as given on stackoverflow. Following is my code for index.rst and config.py:- index.rst

Welcome to sample documentation!
   ===
   === === === === === === === === === === === ==
   Docs - Sample repository

   ..autosummary::
   : toctree: _autosummary: template: custom - module - template.rst: recursive:

   extract
transform
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

extensions = [
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
   'sphinx.ext.coverage',
   'sphinx.ext.napoleon',
   'sphinx.ext.viewcode'
]

templates_path = ['_templates']
exclude_patterns = ['_build', '_templates']

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
autosummary_generate = True

Let’s say we have the following project structure:

└──
package└── submodule├── __init__.py└── subsubmodule└── subsubsubmodule.py

package.submodule.init.py

from package.submodule.subsubmodule.subsubmodule
import Class

This prevents the auto summaries for the classes, functions and methods of the package.submodule.subsubmodule.subsubsubmodule from being generated and showing up using the :recursive: option. I still have to add the following code to make them show up manually:

   ..rubric::Classes

      ..autosummary::
      : toctree:
      : template: custom - class - template.rst

   Class

      ..rubric::Functions

      ..autosummary::
      : toctree:

      function_1