supriya-project / uqbar

Tools for building documentation with Sphinx, Graphviz and LaTeX
https://supriya-project.github.io/uqbar
MIT License
13 stars 7 forks source link

Add uqbar_api_omit_inheritance_diagrams config parameter. #59

Closed trevorbaca closed 2 years ago

trevorbaca commented 2 years ago

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.

trevorbaca commented 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.

josiah-wolf-oberholtzer commented 2 years ago

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

josiah-wolf-oberholtzer commented 2 years ago

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

josiah-wolf-oberholtzer commented 2 years ago

@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.

trevorbaca commented 2 years ago

Subclassing worked, thanks! Everything good 👍