Generate great documentation - Githubissues

maliput / maliput_infrastructure

Driving simulation repository for workspace .repo indexes, Makefiles, etc.

BSD 3-Clause "New" or "Revised" License

0 stars 2 forks source link

Generate great documentation #229

Closed agalbachicar closed 2 years ago

agalbachicar commented 3 years ago

Part of #135

Should document into maliput_documentation (logging here because it affects repositories out of the scope of maliput repos now):

[x] Make doxygen documentation errors to be failures #227
[x] Define whether to include delphyne repos into doxygen documentation. If yes, do it! https://github.com/ToyotaResearchInstitute/maliput_infrastructure/issues/229#issuecomment-913712159
[x] Python documentation (of bindings, demos, delphyne, etc.) https://github.com/ToyotaResearchInstitute/maliput_py/pull/19
[x] maliput_integration applications https://github.com/ToyotaResearchInstitute/maliput_infrastructure/issues/229#issuecomment-915356528
[x] maliput_malidrive xodr tools. https://github.com/ToyotaResearchInstitute/maliput_malidrive/pull/170
[x] maliput_malidrive forensics ->https://docs.google.com/document/d/1R1GYt0QkzUOdnyZxz2QhOh1tq6s7iLIu07Gc_REqTj0/edit#heading=h.5h8y2rlp1xds
[x] delphyne_demos
[x] maliput visualizer
[x] maliput plugin architecture https://github.com/ToyotaResearchInstitute/maliput/pull/441

francocipollone commented 3 years ago

Some comments

1 - For maliput_py we are building docs but dsim_docs_bundler isn't collecting them. At the moment there is no sensitive documentation because the package only contains bindings. Probably creating a doc file in maliput_py, (maliput_bindings.h) just to document bindings and let doxygen parse it could be the way to go.

2 -

For the apps like maliput_malidrive xodr tools. we probably could add a doc at maliput_malidrive/src/applications commenting about the applications so as let doxygen to parse it.
For all the applications we could have a page in maliput_documentation where from there you can link to the docs you have locally in each repository.

3 - We should also document plugin architecture focused on the RoadNetwrok plugin.

francocipollone commented 3 years ago

Define whether to include delphyne repos into doxygen documentation. If yes, do it!

It was agreed to add it.

[x] Enable doc generation for delphyne-repos.
- [x] delphyne https://github.com/ToyotaResearchInstitute/delphyne/pull/801
- [x] delphyne_gui https://github.com/ToyotaResearchInstitute/delphyne_gui/pull/453
- [x] delphyne_demos https://github.com/ToyotaResearchInstitute/delphyne_demos/pull/22
[x] Integrate doxygen files into maliput_documentation: See documentation.rst
--> Delphyne repos will become part of maliput_documentation dependencies https://github.com/ToyotaResearchInstitute/maliput_documentation/pull/57
- [x] Update repos_index files given that maliput_documentation repo shouldn't be part of maliput.repos because of its new dependency to delphyne_repos. https://github.com/ToyotaResearchInstitute/repos_index/pull/36
- [x] Update maliput_infrastructure CI given the new maliput_documentation dependency. https://github.com/ToyotaResearchInstitute/maliput_infrastructure/pull/231

francocipollone commented 3 years ago

maliput_integration applications

[x] maliput_to_string https://github.com/ToyotaResearchInstitute/maliput_integration/pull/84
[x] maliput_query https://github.com/ToyotaResearchInstitute/maliput_integration/pull/85
[x] maliput_to_obj https://github.com/ToyotaResearchInstitute/maliput_integration/pull/90
[x] maliput_to_urdf https://github.com/ToyotaResearchInstitute/maliput_integration/pull/93
[x] maliput_derive_lane_s_routes https://github.com/ToyotaResearchInstitute/maliput_integration/pull/94
[x] maliput_measure_load_time https://github.com/ToyotaResearchInstitute/maliput_integration/pull/97
[x] maliput_to_string_with_plugin https://github.com/ToyotaResearchInstitute/maliput_integration/pull/95
[x] maliput_loader.py/maliput_to_string_with_plugin.py https://github.com/ToyotaResearchInstitute/maliput_integration/pull/95
[x] Links tutorials from maliput_documentation page https://github.com/ToyotaResearchInstitute/maliput_documentation/pull/65

agalbachicar commented 3 years ago

@francocipollone I think we are only missing the maliput_visualizer documentation, right? Isn't it partially covered by the Delphyne Guide 2 as delphyne demos are?

francocipollone commented 3 years ago

@francocipollone I think we are only missing the maliput_visualizer documentation, right? Isn't it partially covered by the Delphyne Guide 2 as delphyne demos are?

maliput_viewer isn't documented in the Delphyne guide. Would you want me to add a section with that information?

agalbachicar commented 3 years ago

Let's do it to wrap up this effort.

francocipollone commented 3 years ago

Let's do it to wrap up this effort.

Done.