exhale

exhale copied to clipboard

Hi!

I've created a small extension which monkey patches exhale to support multiple doxygen projects.

Would you be interested in incorporating this into exhale as a default feature? If so I'll send you a pull request with the changes required.

Thanks!

HELL YES!!! I'm impressed by how seamlessly you pulled it off! This made me particularly happy for some reason

https://github.com/mithro/sphinx-contrib-mithro/blob/7dcf8d51bab6db1404d38ae2c03a4390ca5ea624/sphinx-contrib-exhale-multiproject/exhale_multiproject_monkeypatch.py#L102

Admittedly, the current requirements on exhale_args pretty much assume only one project. I'll need to think a little bit about how we should introduce this change so that existing projects still work. The idea would be to take things that are project-specific and take them out of exhale_args, moving them to exhale_projects like the monkey patch does.

Maybe check if exhale_projects exists. If not, emit a warning encouraging to update, but auto-populate an entry in exhale_projects? I'll need to go through all of the configs and identify what should be moved.

Question for You: I don't know verilog at all, are the breathe directives such as .. doxygenclass:: etc actually working for you?

Since this is going to be a big change, and the monkey patch works really well, I'll try and bang out #28 this week while thinking about this change in the background.

Hey @mithro, @tkhyn gave me an excellent head start on the testing framework and we've been baking in the future multi-project support possibility in the framework. I'd like to start brainstorming on the best way to specify projects.

1. I intend to remove the users' need to specify both breathe utilities and exhale. Exhale should be able to auto-populate those. This way people don't have to do

   breathe_projects = { ... }
   exhale_projects = { ... }
   

   It's really annoying to have to specify both!

2. I think for many cases, there are a lot of configuration variables that can be shared. For example

   exhale_projects = {
       "shared_args": {
           "createTreeView": True,
           "rootFileTitle": "%PROJECT_NAME% Api", # kind of like how `argparse` does it
           "rootFileName": "%PROJECT_NAME%.rst" # this may be a bad idea (spaces, special characters etc)
       },
       "Alpha Framework": { "containmentFolder": "./api/alpha" }
   }
   

   That sort of thing. The idea being that shared_args is a reserved "project name" that allows you to only need to specify the core tailoring once, minimizing the amount of repeated stuff needed to be entered for each specific project. Projects can also override, e.g. Alpha Framework can just as easily set createTreeView to False to disable it just for that project.

There are some things for testing that need to change toward the project (primarily not storing configurations at module scope in exhale.configs), so if anything comes into mind in terms of specifying projects I'd love to hear people's thoughts. This is still the planning phase.

I think that using shared_args is not optimal. Why not simply use 2 options like that:

exhale_config = {  # could be renamed to exhale_global or exhale_params ...
    "createTreeView": True,
    "rootFileTitle": "%PROJECT_NAME% Api",
    "rootFileName": "%PROJECT_NAME%.rst"
}
exhale_projects = {
    "Alpha Framework": { "containmentFolder": "./api/alpha" }
}

It would be cleaner and clearer in my view.

Regarding special chars in filenames (spaces should not be a problem even on Unix normally) or this sort of problems, it should be reasonably easy to add checks when parsing the configuration.

Update: where I'm moving is to only require "doxygenStripFromPath" (unfortunately, there's no way around this one and probably never will be) and auto-populate the other three required entries. This should allow me to create breathe_projects myself, generating to {sphinx build dir}/doxygen/{project}/xml.

If you think the below changes are not ideal, please speak up! Or if you have suggestions.

Note 1: These changes will assert that project names match alphanumeric, _, -, and spaces. This may be a problem for somebody one day, but is pretty reasonable to assert in my opinion. The requirements come from needing to be able to create a directory with the same name.

Note 2: If users want to run Doxygen manually, they must populate "exhaleExecutesDoxygen": False (now True by default), and specify breathe_projects (since I need to know where the XML output is).

1. exhale_args is in conf.py. Minimum specification is

   exhale_args = {
       # I'm adding monkey patching to take `exhaleDoxygen*` => doxygen dict
       "doxygen": {
           "stripFromPath": "../include",
           "stdin": "INPUT = ../include"
       }
   }
   

   • Creates "./api/library_root.rst" or "./source/api/library_root.rst" (depending on sphinx configs).

   • RST title on library_root: Library API.

     • Can always be overridden with "rootFileTitle" entry.

   • Toctree:

     .. toctree::
        :max-depth: 2
     
        about
        api/library_root
     

2. exhale_projects is in conf.py and optionally exhale_global_args:

   exhale_global_args = {
       "doxygen": {"stripFromPath": "../include"}
   }
   exhale_projects = {
       "first": {
           "doxygen": {"stdin": "INPUT = ../include/first"}
       },
       "second": {
           "doxygen": {"stdin": "INPUT = ../include/second"}
       }
   }
   

   • Creates ./api/first/library_root.rst with title first Library API and ./api/second/library_root.rst with title second Library API.

     • Can still be overridden per-project with "rootFileTitle", or
     • Special key exhale_global_args["rootFileTitleGenerator"] is auto-populated to be "{project} Library API". Only allowed in exhale_global_args, but can be changed as desired.

   • Toctree:

     .. toctree::
        :max-depth: 2
     
        about
        api/first/library_root
        api/second/library_root
     

@svenevs I'm currently trying to use the monkeypatch provided by @mithro and everything seems to work fine except for the part where Breathe expects a :project: in every directive. Is there an easy way to make exhale add :project: ${breathe_default_project} when generating the breathe output? The monkey patch already makes everything else works as far as I can see :)