Building documentation

[albert-github]

I see that the documentation is still not build 'out of source' (at least I could not find it), it would be better if the building of the documentation finds place 'out of source'.

[weslleyspereira]

Hi. Could you be more specific about the suggestion? Thanks!

[albert-github]

It is hard to tell after such a time.
I did some digging and what I see is that in the Doxyfile the in INPUT is set to . and the OUTPUT_DIRECTORY is set to DOCS, meaning that you have to start the documentation generation in the root of the repository tree and that the results will be in the the sub-directory explore-html (as this directory is set as HTML_OUTPUT of the DOCS directory.
When using cmake I would have expected that there are some references to the SOURCE_DIR and the BINARY_DIR in the Doxyfile.

In the CMakeLists.txt I see some references to doxygen variables but there is no further mentioning of them in the repository

[weslleyspereira]

Thanks for the explanation!

The CMakeLists.txt currently does not use the Doxyfile. So, in terms of building LAPACK with CMake, we don't need the Doxyfile file. I have just removed the file and generated the documentation with no problems. Moreover, CMake does use ${CMAKE_CURRENT_BINARY_DIR}/DOCS as the output for the documentation. So, I think CMake is just fine.

Now, if we use Makefile, I do see the line cat DOCS/Doxyfile ; echo "OUTPUT_DIRECTORY=$(DOCSDIR)". And DOCSDIR is usually set to DOCSDIR = $(TOPSRCDIR)/DOCS. So, the documentation would be built in the folder DOCS. I think this makes sense for Makefile, since there is no separate build directory.

The last use case is if one wants to build the documentation running doxygen directly from command line. In this case, one must run the command from the root LAPACK dir or modify the Doxyfile directly. I don't see a problem with that either, since both Makefile and CMake would still work as expected in terms of generating the documentation in the correct place.

So, I actually don't think we need to change anything.

[albert-github]

Well the problem I always have is that generated information is mixed into sources directory (repository directory) and disturbs the differences between generated files and the original source or even that they can be accidentally added to the repository.

I think that for the Makefile it would also make sense to create a separate directory for the resulting documentation (I hope that Lapack also places the object files / libraries / executable in dedicated directories outside the the source tree)

(as a side note it is a pity that there are for Lapack still 2 build systems used, the old make system with the Makefiles and cmake, although cmake can also use make again under the hood)

[weslleyspereira]

I understand your concern, and I also don't like mixing source with generated files. Unfortunately, the Makefile build system in LAPACK is still mixing source and object files. At least the libraries remain separate inside the lib directory.

There is a discussion about the build systems in the library: #488. In the end, it was decided to keep Makefile and CMake. I think CMake has received more attention from the community.