search

roboticslab-uc3m / questions-and-answers

A place for general debate and question&answer
https://robots.uc3m.es/developer-manual/appendix/repository-index.html
2 stars 0 forks source link

Make dox target via YCM goodies #79

Closed PeterBowman closed 5 years ago

PeterBowman commented 5 years ago

YCM 0.10 (unreleased) pulls CMake's v3.9 FindDoxygen module (https://github.com/robotology/ycm/issues/7), which provides a handy doxygen_add_docs function for adding a custom target that runs Doxygen. Usually, we need to cd into the doc/ directory and manually run doxygen; sometimes (rarely) this target is added through CMake code (see amor-api).

PeterBowman commented 5 years ago

If I understood this correctly, there is no need to keep a Doxyfile around in doc/ anymore - it's automatically generated by doxygen_add_docs().

PeterBowman commented 5 years ago

I'm currently testing this in kinematics-dynamics: https://github.com/roboticslab-uc3m/kinematics-dynamics/commit/6976f81f0344a8abfe1cd556d9ced9d382314148. The Doxyfile is no longer needed, CMake will take care of generating a convenient target with the supplied name (I've picked dox) that, when run (make dox), will result in the creation and processing of a Doxyfile.dox. In addition to having doxygen available, admins now need to install CMake (3.5+) and YCM 0.10 (https://github.com/roboticslab-uc3m/questions-and-answers/issues/82). You need not to configure the whole project, just the doc/ tree, i.e. cd into doc/build/ and proceed with cmake .. && make dox (https://github.com/roboticslab-uc3m/kinematics-dynamics/commit/cad631cdc8c55beaa79a0609666584ff8f5096f6). It's good practice to clean the build directory whenever updating docs: make clean && make dox.

Most doxygen options can be tweaked from CMake code in an intuitive manner, see doc/CMakeLists.txt. I strived to configure doxygen in the way it was done prior to these changes. Notable differences:

In addition, GROUP_NESTED_COMPOUNDS was not used in former doxygen versions, modern ones set it to NO. It is now enabled.

I've uploaded this patch on server (robots.uc3m.es), CMake had to be upgraded from 3.2.2 to 3.5.2 so that YCM 0.10 could be installed afterwards. Also, the symlink in htdocs now points at doc/build/.

PeterBowman commented 5 years ago

Oh, by the way. Markdown parsing is enabled by default, which means that .md files located at doc/ are processed by doxygen: Related Pages.

PeterBowman commented 5 years ago

Markdown code blocks are not supported by Doxygen 1.8.9.1 (Ubuntu Wily, 15.10). They are rendered correctly by Doxygen 1.8.11 (Ubuntu Xenial, 16.04), though.

PeterBowman commented 5 years ago

I had to end Markdown links with a slash so that Doxygen (1.8.11) can render them correctly: https://github.com/roboticslab-uc3m/kinematics-dynamics/commit/8c4fce6589e07e57aac050bea3c7f497de6cb414. Only affects URLs that end with a file extension, that is:

PeterBowman commented 5 years ago

Most repos done, I ignored those which hadn't undergone a CMake review in the past.

PeterBowman commented 5 years ago

I missed a cmake .. instruction between these lines: ref. Will do soon.

PeterBowman commented 5 years ago

I missed a cmake .. instruction between these lines: ref. Will do soon.

Done everywhere as in https://github.com/roboticslab-uc3m/kinematics-dynamics/commit/9ba9ae03156b18efdf90d15d8c9b15db3576047f.

PeterBowman commented 3 years ago

We don't need YCM anymore in our new GitHub Actions infrastructure: https://github.com/roboticslab-uc3m/questions-and-answers/issues/91#issuecomment-797488015.