mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
0869680435
Regression of @99bcf20: Since Sphinx 1.2.1 (commit sphinx-doc/sphinx@574a796), sphinx.ext.autosummary overwrites custom-set documenters. This is not a particularly elegant solution, but none of the events from sphinx.ext.autodoc allows editing a function's name. Subclassing other autodoc classes also appears to be quite challenging.
50 lines
1.5 KiB
Python
50 lines
1.5 KiB
Python
# -*- coding: utf-8 -*-
|
|
'''
|
|
:codeauthor: :email:`Pedro Algarvio (pedro@algarvio.me)`
|
|
|
|
|
|
saltautodoc.py
|
|
~~~~~~~~~~~~~~
|
|
|
|
Properly handle ``__func_alias__``
|
|
'''
|
|
|
|
# Import Sphinx libs
|
|
from sphinx.ext.autodoc import FunctionDocumenter as FunctionDocumenter
|
|
|
|
|
|
class SaltFunctionDocumenter(FunctionDocumenter):
|
|
'''
|
|
Simple override of sphinx.ext.autodoc.FunctionDocumenter to properly render
|
|
salt's aliased function names.
|
|
'''
|
|
|
|
def format_name(self):
|
|
'''
|
|
Format the function name
|
|
'''
|
|
if not hasattr(self.module, '__func_alias__'):
|
|
# Resume normal sphinx.ext.autodoc operation
|
|
return super(FunctionDocumenter, self).format_name()
|
|
|
|
if not self.objpath:
|
|
# Resume normal sphinx.ext.autodoc operation
|
|
return super(FunctionDocumenter, self).format_name()
|
|
|
|
if len(self.objpath) > 1:
|
|
# Resume normal sphinx.ext.autodoc operation
|
|
return super(FunctionDocumenter, self).format_name()
|
|
|
|
# Use the salt func aliased name instead of the real name
|
|
return self.module.__func_alias__.get(self.objpath[0], self.objpath[0])
|
|
|
|
|
|
def setup(app):
|
|
def add_documenter(app, env, docnames):
|
|
app.add_autodocumenter(SaltFunctionDocumenter)
|
|
|
|
# add_autodocumenter() must be called after the initial setup and the
|
|
# 'builder-inited' event, as sphinx.ext.autosummary will restore the
|
|
# original documenter on 'builder-inited'
|
|
app.connect('env-before-read-docs', add_documenter)
|