Revamp default Sphinx project #33
Conversation
|
FYI @clalancette. BTW, this project is not passing its own tests in |
| "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( | ||
| lambda kind: [":content-only:", ":no-link:"] if kind == "page" else []), |
There was a problem hiding this comment.
IIRC, this also changes the behavior when there is a different (not :doxygenpage:) directive. As in, other directives such as :doxygenfunction: wouldn't render correctly with this mapping, and I think you have to provide mappings for each such directive. I will confirm whether that's true in a future comment.
There was a problem hiding this comment.
💯 in general for the behavior this should give otherwise though.
|
This pull request has been mentioned on ROS Discourse. There might be relevant details there: https://discourse.ros.org/t/ros-2-tsc-meeting-minutes-2021-10-28/22947/1 |
|
This is ready to go @clalancette. |
|
This pull request has been mentioned on ROS Discourse. There might be relevant details there: https://discourse.ros.org/t/ros-2-tsc-meeting-minutes-2021-11-18/23209/1 |
| } | ||
|
|
||
| with open(os.path.join(directory, 'conf.py'), 'w+') as f: | ||
| f.write(default_conf_py_template.format_map(template_variables)) | ||
|
|
||
| root_title = f'Welcome to {package.name} documentation' |
There was a problem hiding this comment.
I think this would read better as:
Welcome to the documentation for {package.name}
There was a problem hiding this comment.
Agreed. See d942673.
| # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved. | ||
| # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( | ||
| # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []), | ||
| "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( |
There was a problem hiding this comment.
Did we ever resolve @aprotyas issue with this? Quoting:
IIRC, this also changes the behavior when there is a different (not :doxygenpage:) directive. As in, other directives such as :doxygenfunction: wouldn't render correctly with this mapping, and I think you have to provide mappings for each such directive. I will confirm whether that's true in a future comment.
There was a problem hiding this comment.
It's funny, exhale documentation is misleading here. If utils.makeCustomSpecificationsMapping yields an empty list for the specs of given directive, it'll use Breathe defaults, which are not the same as Exhale defaults (https://github.com/svenevs/exhale/blob/bbb5d71f126d1281a8c4f1729c218c236f44457b/exhale/utils.py#L185). I can change this to match Exhale defaults though.
There was a problem hiding this comment.
The Exhale defaults are not bad, but those defaults are only for the class and struct kinds.
It would be nice to pay the one-time cost of a rosdoc2_specsMapping dictionary that lets us control the directive of all kinds that are of interest. It also makes for more extensibility:
rosdoc2_specsMapping = {
'page': [':content-only:'],
**dict.fromkeys(['class', 'struct'], [':members:', ':protected-members:', ':undoc-members:']),
# other kind-specs mapping
}
"customSpecificationsMapping": utils.makeCustomSpecificationsMapping(
lambda kind: rosdoc2_specsMapping.get(kind, [])),There was a problem hiding this comment.
That looks reasonable to me. See befbade.
- Modify default index - Use Exhale generated index - Change Exhale configuration Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
- Expose exhale specs mapping as a rosdoc2 setting - Use exhale defaults as rosdoc2 defaults Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
befbade to
3bd61d0
Compare
|
Rebased and ready for another round of reviews. |
This patch:
Requires svenevs/exhale#114.