Please allow for some post-processing about exhale

[svenevs]

Hahahaha LOL oh how much I agree with you! So I'm open to suggestions, but I have learned that function objects can actually be pickled. It's just that a detail about how Sphinx parses conf.py means that you cannot pickle a function defined in conf.py itself. Meaning in the future with the planned writer interface sometime with 1.x, I should be able to let users take very fine-grained control over how things are generated.

What exactly do you want to change? It will help me understand how / where Exhale can let you hook into things.

That said, there is this "secret" saving of the ExhaleRoot object that the testing framework actually relies on to make comparisons.

exhale/exhale/deploy.py

Lines 428 to 429 in ab69386

	# allow access to the result after-the-fact
	configs._the_app.exhale_root = textRoot

So I think you can do something like this in conf.py

def my_postprocessing(app):
    exhale_root = app.exhale_root
    the_function = None
    for node in exhale_root.all_nodes:
        if node.kind == "function" and node.name == "function::you::wanna::change":
            the_function = node
            break

    if not the_function:
        raise RuntimeError("couldn't find it...")

    file_path = os.path.join(exhale_root.root_directory, the_function.file_name)
    # open / edit etc

I didn't test that but that should be close, but the order matters -- exhale has to go first, so I think what you do is below that

# in conf.py, it makes your `conf.py` an "extension"
def setup(app):
    app.setup_extension("exhale")
    app.connect("builder-inited", my_postprocessing)

What that should do is say "hey I need exhale to run first", then in the same event (builder-inited) run my_postprocessing.

Some small notes:

1. app.exhale_root will disappear in v1.0.0, it's undocumented because it was a temporary hack.

2. Note that you have to do os.path.join(exhale_root.root_directory, something). By the time you get access to exhale_root the regrettable function has been called (also going away in 1.0.0, this was a dumb thing for me to do...)

   exhale/exhale/graph.py

   Lines 3027 to 3038 in ab69386

   	def gerrymanderNodeFilenames(self):
   	'''
   	When creating nodes, the filename needs to be relative to ``conf.py``, so it
   	will include ``self.root_directory``. However, when generating the API, the
   	file we are writing to is in the same directory as the generated node files so
   	we need to remove the directory path from a given ExhaleNode's ``file_name``
   	before we can ``include`` it or use it in a ``toctree``.
   	'''
   	for node in self.all_nodes:
   	node.file_name = os.path.basename(node.file_name)
   	if node.kind == "file":
   	node.program_file = os.path.basename(node.program_file)

3. You only have to do that join for leaf documents (the ones the breathe directives are actually on). The top-level documents for library root etc should be safe to just access these fields directly from exhale_root:

   exhale/exhale/graph.py

   Lines 908 to 911 in ab69386

   	self.full_root_file_path = os.path.join(self.root_directory, self.root_file_name)
   	self.class_hierarchy_file = os.path.join(self.root_directory, "class_view_hierarchy.rst")
   	self.file_hierarchy_file = os.path.join(self.root_directory, "file_view_hierarchy.rst")
   	self.unabridged_api_file = os.path.join(self.root_directory, "unabridged_api.rst")

4. Don't get trapped by my extremely confused bookeeping variables. By the time you get access, exhale_root.class_like does not contain all classes and structs! This is a detail specific to making the tree view easier to generate. It only contains top-level things by the time you get it. So if you want to change all class / struct pages:

   all_class_like = [node for node in exhale_root.all_nodes if node.kind in ["class", "struct"]]
   for node in all_class_like:
       file_path = os.path.join(exhale_root.root_directory, node.file_name)
       # do stuffs

Hope that makes sense. Does this enable you to bypass what you want?

[svenevs]

Ooops I didn't mean to finish that. What I do not know: if you are guaranteed that your custom my_postprocessing will execute after exhale does (I don't think this is what setup_extension actually does, it probably only calls setup(app) and you may be relying on Sphinx registering 'builter-inited' handlers sequentially).

But there is a different Sphinx event that may actually be much easier for you to post-process anything with, it depends on what you need to do I guess. It might be best to connect to the 'source-read' event instead. You should also be guaranteed that app.exhale_root (until v1.0.0) will exist by that point.

[mquinson]

I must confess that I'm not using exhale anymore. At some point, I realized that I wanted to have the full control of how things are displayed, and thus, exhale was not adapted to my needs. Thanks for this great project anyway. That's still a great application for the ones less control-freak than me...

[svenevs]

Sorry to see you go, but I fully understand and that's a completely valid complaint about exhale. If you're willing to enumerate the things you would like control over I'd be grateful. I've got a prototype for how to pass controls to users for writing their own class, but right now most of my efforts are focused on fixing breathe which has some big updates needed if it is to remain viable.

I'm leaving this open as a reminder that while exhale provides some reasonable defaults, it's almost 100% inflexible with respect to people wanting to change things. Particularly on a per-compound basis. Users need control over this!