Comments (5)
HELL YES!!! I'm impressed by how seamlessly you pulled it off! This made me particularly happy for some reason
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.
from exhale.
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.
from exhale.
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).
-
exhale_args
is inconf.py
. Minimum specification isexhale_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.
- Can always be overridden with
-
Toctree:
.. toctree:: :max-depth: 2 about api/library_root
-
-
exhale_projects
is inconf.py
and optionallyexhale_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 titlefirst Library API
and./api/second/library_root.rst
with titlesecond 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 inexhale_global_args
, but can be changed as desired.
- Can still be overridden per-project with
-
Toctree:
.. toctree:: :max-depth: 2 about api/first/library_root api/second/library_root
-
from exhale.
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.
-
I intend to remove the users' need to specify both
breathe
utilities andexhale
. Exhale should be able to auto-populate those. This way people don't have to dobreathe_projects = { ... } exhale_projects = { ... }
It's really annoying to have to specify both!
-
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 setcreateTreeView
toFalse
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.
from exhale.
@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 :)
from exhale.
Related Issues (20)
- ignore file extensions in directory? HOT 6
- "createTreeView":True with RTD theme does not show Class Hierarchy HOT 1
- Operator>>, <<, -> overloading bug HOT 4
- Unable to resolve function HOT 1
- Warnings caused by missing newlines in exhale output HOT 3
- LaTeX in \f$ swallows \n newlines HOT 2
- Allow root file to be excluded and set filename of hierarchy files HOT 1
- Replace collapsible list JavaScript with details/summary HOT 1
- Does it work for C projects? HOT 1
- Module Index Error 404 page HOT 1
- Exhale seems to eat asterisk-chars '*' HOT 1
- Exhale does not find functions with weird data types
- Hard-coded 'Class' and 'Classes' even for C
- Allow fully qualified enum, class, structs titles
- Fixup packaging requirements HOT 8
- Windows path length issues HOT 4
- no coverage uploaded for master HOT 1
- KeyError: 'concept' when listing nodes to console HOT 1
- Problem with Sphinx 7
- Github action fails HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from exhale.