Closed trevorbaca closed 2 years ago
CI fails on two tests prior to the addition of this PR. Those same two tests continue to fail on this PR.
The Uqbarian way to handle this is to roll your own ModuleDocumenter
subclass (which creates the restructuredText output for a single Python module) and have it omit the inheritance diagram, then configure Sphinx to use that class instead of whichever ModuleDocumenter
subclass it's currently using (probably uqbar.SummarizingModuleDocumenter
).
I'm doing something along these lines already in Supriya, where I no longer wanted to see subsections ("classes", "functions"), auto-summaries, or inheritance diagrams (although I might add those back eventually).
My module documenter subclass lives in supriya.ext.apis
: https://github.com/josiah-wolf-oberholtzer/supriya/blob/main/supriya/ext/api.py#L57-L69
And the knob for using it is here: https://github.com/josiah-wolf-oberholtzer/supriya/blob/main/docs/source/conf.py#L63
The custom module documenter I'm using there is based off of the "vanilla" one from Supriya, which Abjad never used, and which creates much simpler output: https://github.com/josiah-wolf-oberholtzer/uqbar/blob/main/uqbar/apis/ModuleDocumenter.py#L104-L109
Example of the output here: http://josiahwolfoberholtzer.com/supriya/api/supriya/realtime/nodes.html
And FWIW, the only thing that Supriya's custom module documenter is doing differently from its parent class is suppressing the visibility of the Sphinx TOC inside the document body; it still appears in the sidebars.
Parent class: https://github.com/josiah-wolf-oberholtzer/uqbar/blob/main/uqbar/apis/ModuleDocumenter.py#L133 Child class: https://github.com/josiah-wolf-oberholtzer/supriya/blob/main/supriya/ext/api.py#L62
@trevorbaca let me know if the information above is helpful. I can probably find time for a PR to Abjad to address the desired changes in a clean and simple way.
Subclassing worked, thanks! Everything good 👍
Uqbar 0.5.9 appears to provide no way for users to suppress the generation of inheritance diagrams during API build. (Removing uqbar.sphinx.inheritance from the list of extensions in conf.py generates errors during API build because SummarizingModuleDocumenter continues to write inheritance-diagram directives into .rst files even when no inheritance diagrams are produced.)
This PR adds an uqbar_api_omit_inheritance_diagrams config parameter. The parameter is settable in conf.py, and defaults to false. When true, APIBuilder sets an omit_inheritance_diagrams property on module documenter objects; SummarizingModuleDocumenter knows about this parameter and suppresses inheritance-diagram directives in .rst output when true.