Re: [CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
Le jeu. 21 févr. 2019 à 06:19, Timothy Wrona a écrit : > > Either way having it as an "index.html" file somewhere on the hard-disk is > not very intuitive. It would make much more sense for it to be on a web > server where you can access it with a sensible URL. > Unless it's linked from some front page you know users often go to, I don't see why http://some.server/doc/mylibrary/index.html is more "intuitive" than file://some/directory/mylibrary/index.html. The difference between the two is sharing vs not, it's not about "intuitiveness". BTW your questions are really not clear on the topic of sharing. The problem of a developer building documentation without realizing it is very different from the problem of user not building anything, even when the latter is not curious about documentation either. PS: I suggested some cmake fine-tuning on stackoverflow. -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
Re: [CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
On 21/02/2019 14:18, Timothy Wrona wrote: Perhaps there is a standard location to "install" the documentation when running the install command for a project? This collection builds and installs the documentation into a standard location, as well as reporting undocumented code. Feel free to copy and adapt. Could be turned into an official module if there was interest for a generic solution for doxygen docs building and installing. https://gitlab.com/codelibre/ome-common-cpp/blob/master/docs/doxygen/CMakeLists.txt https://gitlab.com/codelibre/ome-common-cpp/blob/master/docs/doxygen/api.dox.cmake https://gitlab.com/codelibre/ome-common-cpp/blob/master/cmake/Doxygen.cmake https://gitlab.com/codelibre/ome-common-cpp/blob/master/cmake/DoxygenCheck.cmake Dependent modules can also cross-reference documentation for modules they depend upon. See lines 44-56 for overriding the tagfiles, which are then substituted into the generated doxyfile configuration. This could also be generalised to make into a reusable module. https://gitlab.com/codelibre/ome-files-cpp/blob/master/docs/doxygen/CMakeLists.txt You can see this on the GitLab documentation pages (linked from the README) for the project(s) in question. Hope that's potentially of some use for anyone interested. Roger -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
Re: [CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
Hi Timothy, This is not something I'm very familiar with, but maybe I can still add a little to the discussion by answering both of your messages together. On 21/2/2019 10:18 PM, Timothy Wrona wrote: Perhaps there is a standard location to "install" the documentation when running the install command for a project? Either way having it as an "index.html" file somewhere on the hard-disk is not very intuitive. It would make much more sense for it to be on a web server where you can access it with a sensible URL. You're right that it isn't intuitive, but then you're assuming that users will all install a (Apache, etc.) web server. And many users do not. If you're doing cross-platform development, then I am fairly sure that most of the people I know who use Microsoft Windows do not install a web server. On my Ubuntu-based computer, I have installed a local version of the Boost library. The HTML documentation is installed in: $BOOST_ROOT/doc/html/ . In my case, $BOOST_ROOT is /usr/local/boost_/, but some people might install it in /opt, for example. As for your 3 questions, I don't know the definitive answer but my gut feeling is: > 1. > > Is there a standard location to put the documentation once it is built > where it makes it very clear to the users of a library that documentation > is available for a library? For packages installed using Ubuntu's package management system, documentation tends to go to /usr/share/doc/ or /usr/share/man/. But I'm sure the path is different for CentOS, RedHat, etc. If you're not installing software through a package manager, then the documentation probably goes into /usr/local or /opt (See: https://unix.stackexchange.com/questions/11544/what-is-the-difference-between-opt-and-usr-local). For software that I've developed myself, I've placed the documentation together with the software, similar to the Boost library. That is, within the root directory, I threw it into a directory called doc/. If sysadmin access is required and it goes into /usr/local//, then like Boost, it would go inside that directory. With other people's programs that I've downloaded myself, I normally look in the root directory (of that program) for a doc/ directory too. So, perhaps the answer to your question about "standard location" is to just ask yourself if your role was reversed -- i.e., you're just a user -- where would you look for documentation? > 2. > > How can I ensure that every time my library is built, the documentation > will be *automatically *updated and placed in this standard location? Since this is your software and you wrote the CMake file, as long as you've defined and then fixed the installation target from version to version, then it should be ok. I don't know what kind of automation you were looking for. Someone still has to do a "cmake ..; make; make install" or something like that. You're not talking about automation along the lines of some cron job, are you? > 3. > > Is there any standard way to keep past versions of documentation for > reference in case someone is using an earlier version of the library? I think when you've asked "standard way", it sounds like you're looking for Doxygen and/or CMake having standardized the location. But, based on my examples above, it seems it is OS dependent. And it depends whether you're distributing the source files or the binaries only (i.e., like an Ubuntu/Debian .deb package). In the case of the former, you've defined it using your CMake file. In the latter case, you've compiled it and then wrote some instructions for Debian's package management software so that the documentation goes into /usr/share/doc, /usr/share/man/, etc. Just my 2 cents...I'm happy to hear what others think. Ray -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
Re: [CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
Perhaps there is a standard location to "install" the documentation when running the install command for a project? Either way having it as an "index.html" file somewhere on the hard-disk is not very intuitive. It would make much more sense for it to be on a web server where you can access it with a sensible URL. On Thu, Feb 21, 2019 at 1:44 AM Alan W. Irwin wrote: > On 2019-02-20 17:52-0500 Timothy Wrona wrote: > > > I have worked on multiple C++ libraries that are built with CMake and run > > Doxygen to generate HTML documentation. In every one of these libraries, > > the documentation get's built into an "html" folder in the CMake "build" > > directory and never gets looked at by anyone. > > > > *Because let's be honest, most people don't like to read documentation at > > all - let alone search for it.* > > > > This leads to a few questions: > > > > 1. > > > > Is there a standard location to put the documentation once it is built > > where it makes it very clear to the users of a library that > documentation > > is available for a library? > > 2. > > > > How can I ensure that every time my library is built, the documentation > > will be *automatically *updated and placed in this standard location? > > 3. > > > > Is there any standard way to keep past versions of documentation for > > reference in case someone is using an earlier version of the library? > > > > I have also posted this question on stack overflow. If you would like, > you > > can answer there instead because it may help a wider audience: > > > https://stackoverflow.com/questions/54796513/automatically-updating-doxygen-documentation-and-making-it-readily-available-to > > I am not aware of any standard responses to your 3 questions above. > > What I do for a couple of my projects that have doxygen-generated > documentation is I have a special custom command/target that copies > the doxygen-generated documentation from the build tree back to a > special directory in the source tree, and I only invoke that target if > I am creating a source tarball. And similarly for DocBook-generated > documentation. Furthermore, I configure my VCS in each case to ignore > those generated directories in the source tree so there are no VCS > complications, yet tarball users get a chance to access the generated > documentation. > > Of course, if someone here has a better or more standardized scheme, I > would like to hear it. > > Alan > __ > Alan W. Irwin > > Programming affiliations with the FreeEOS equation-of-state > implementation for stellar interiors (freeeos.sf.net); the Time > Ephemerides project (timeephem.sf.net); PLplot scientific plotting > software package (plplot.sf.net); the libLASi project > (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); > and the Linux Brochure Project (lbproject.sf.net). > __ > > Linux-powered Science > __ > -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
Re: [CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
On 2019-02-20 17:52-0500 Timothy Wrona wrote: I have worked on multiple C++ libraries that are built with CMake and run Doxygen to generate HTML documentation. In every one of these libraries, the documentation get's built into an "html" folder in the CMake "build" directory and never gets looked at by anyone. *Because let's be honest, most people don't like to read documentation at all - let alone search for it.* This leads to a few questions: 1. Is there a standard location to put the documentation once it is built where it makes it very clear to the users of a library that documentation is available for a library? 2. How can I ensure that every time my library is built, the documentation will be *automatically *updated and placed in this standard location? 3. Is there any standard way to keep past versions of documentation for reference in case someone is using an earlier version of the library? I have also posted this question on stack overflow. If you would like, you can answer there instead because it may help a wider audience: https://stackoverflow.com/questions/54796513/automatically-updating-doxygen-documentation-and-making-it-readily-available-to I am not aware of any standard responses to your 3 questions above. What I do for a couple of my projects that have doxygen-generated documentation is I have a special custom command/target that copies the doxygen-generated documentation from the build tree back to a special directory in the source tree, and I only invoke that target if I am creating a source tarball. And similarly for DocBook-generated documentation. Furthermore, I configure my VCS in each case to ignore those generated directories in the source tree so there are no VCS complications, yet tarball users get a chance to access the generated documentation. Of course, if someone here has a better or more standardized scheme, I would like to hear it. Alan __ Alan W. Irwin Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __ Linux-powered Science __ -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
[CMake] Automatically updating Doxygen documentation and making it readily available to users with CMake
I have worked on multiple C++ libraries that are built with CMake and run Doxygen to generate HTML documentation. In every one of these libraries, the documentation get's built into an "html" folder in the CMake "build" directory and never gets looked at by anyone. *Because let's be honest, most people don't like to read documentation at all - let alone search for it.* This leads to a few questions: 1. Is there a standard location to put the documentation once it is built where it makes it very clear to the users of a library that documentation is available for a library? 2. How can I ensure that every time my library is built, the documentation will be *automatically *updated and placed in this standard location? 3. Is there any standard way to keep past versions of documentation for reference in case someone is using an earlier version of the library? I have also posted this question on stack overflow. If you would like, you can answer there instead because it may help a wider audience: https://stackoverflow.com/questions/54796513/automatically-updating-doxygen-documentation-and-making-it-readily-available-to Thanks, Tim -- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: https://cmake.org/mailman/listinfo/cmake
