How to build just the documentation

albert-github commented 3 years ago

After some questions on doxygen (e.g. https://github.com/doxygen/doxygen/issues/8693 by @couet I got a bit interested in the documentation of ROOT so I looked at it and it looks nice. I thought maybe can I build just the documentation myself. So:

I cloned https://github.com/root-project/root.git
cd root
mkdir build_normal
cd build_normal
cmake ..
??

Unfortunately I could not find a target to build just the documentation.

What is the right procedure to build just the documentation?

I already saw something "strange" in https://root.cern/doc/master/loopdir11_8C.html:

the C\V part and the missing first 2 characters and the not so nice \ (didn't find quickly its source)
the text:

Example of script to loop on all the objects of a ROOT file directory and print on Postscript all TH1 derived objects.

would probably be better:

Example script to loop over all the objects of a ROOT file directory and print in Postscript all the TH1 derived objects.

couet commented 3 years ago

@albert-github thanks for trying out the ROOT documentation. You need root installed to make the ROOT documentation because ROOT documentation uses a filter to create on the fly the picture for all code examples we expose and also to generate the graph of libraries needed by a given class. So to make ROOT do:

clone https://github.com/root-project/root.git
mkdir rootbuild
cd rootbuild
cmake ../root
make -j8
source bin/thisroot.sh // this defines the $ROOTSYS environment variables and more...
cd ../root/documentation/doxygen
Edit Doxyfile to reduce the number of paths in the INPUT variable otherwise it will take a day. Keep ../../io/io for instance
make -j8 // this will creat ~/rootdoc. Open ~rootdoc/html/index.html

We have also this page on our web site which tells a bit the same

Thanks for pointing the wrong page. I will check.

albert-github commented 3 years ago

@couet Thanks for the information.

Is my interpretation correct that the documentation is created from an inplace position (i.e the root/documentation/doxygen) and directly written into the root directory of the user instead of a special build directory, in case this is the case this is, I think, not so nice and should be corrected.

A big pity that a ROOT is required to just for generating the documentation.

I'll give it a try...

Looks like I'm already failing in an early stage on the VDT build as here I get errors about M_PI (and friends)like:

In file included from /cygdrive/e/Programs/github_repositories/normal/root/build_normal/VDT-prefix/src/VDT/include/sincos.h:27,
                 from /cygdrive/e/Programs/github_repositories/normal/root/build_normal/VDT-prefix/src/VDT/include/sin.h:30,
                 from /cygdrive/e/Programs/github_repositories/normal/root/build_normal/VDT-prefix/src/VDT/include/vdtMath.h:6,
                 from /cygdrive/e/Programs/github_repositories/normal/root/build_normal/VDT-prefix/src/VDT/src/vdtMath_signatures.cc:2:
/cygdrive/e/Programs/github_repositories/normal/root/build_normal/VDT-prefix/src/VDT/include/vdtcore_common.h:40:25: error: ‘M_PI’ was not declared in this scope
   40 | const double TWOPI = 2.*M_PI;
      |                         ^~~~

During the cmake build I saw:

-- Looking for VDT
-- Could NOT find Vdt (missing: VDT_INCLUDE_DIR VDT_LIBRARY) (Required is at least version "0.4")
-- VDT not found. Ensure that the installation of VDT is in the CMAKE_PREFIX_PATH
--                Switching ON 'builtin_vdt' option

I'm using Cygwin with g++ (GCC) 10.2.0

couet commented 3 years ago

The ROOT documentation is a big stuff. We want all the pictures in the doc to be generated on the fly. We need ROOT for that.
The documentation is created in ~/rootdoc when you type make in the in $ROOTSYS/documentation/doxygen
Ah with Cygwin .. @bellenot may help.

loopdir.C is fixed here https://github.com/root-project/root/pull/8749 Thanks

bellenot commented 3 years ago

FYI, Cygwin is not supported

albert-github commented 3 years ago

@couet In the CMake build log I see:

-- Checking internet connectivity...
-- Yes

does this mean an internet connection is required? (would not be nice when just building the documentation).

bellenot commented 3 years ago

@couet In the CMake build log I see:
-- Checking internet connectivity...
-- Yes
does this mean an internet connection is required? (would not be nice when just building the documentation).

No, it's just disabling the external packages requiring internet access if there is no internet connection

albert-github commented 3 years ago

@bellenot Thanks for the information.

Is it possible to disable the Internet connection with an option during the cmake (and later build) phase?

I'll give Windows a try (not as nice as now nmake cannot run in parallel ...)

bellenot commented 3 years ago

Is it possible to disable the Internet connection with an option during the cmake (and later build) phase?

Well, no, you can simply unplug (or disable) the internet connection. You can also use the -Dminimal=ON flag to reduce the number of packages

albert-github commented 3 years ago

Well, no, you can simply unplug (or disable) the internet connection.

Not really a good idea

I tried to run cmake for windows, but got some errors here as well, unfortunately stopping my attempts to build ROOT and especially to build the documentation.

bellenot commented 3 years ago

@albert-github BTW, why do you want to do it without internet? And what are the errors you got on Windows?

bellenot commented 3 years ago

And ROOT only support 32 bit. See https://root.cern/install/#build-from-source

AdvaitDhingra commented 3 years ago

You can also build the documentation for just the parts you need by modifying the Doxyfile. That way you don't have to build the whole thing but just the part(s) you want.

albert-github commented 3 years ago

@AdvaitDhingra isn't that what @couet suggested by mentioning to just build the io part? But you still need to set environment variables like in the setting for: EXAMPLE_PATH = $(DOXYGEN_EXAMPLE_PATH) and you need to build the filter programINPUT_FILTER = ./filter. Furthermore I got from the discussion that some images needed to be generated, so ROOT has to be build...

albert-github commented 3 years ago

@bellenot Well just to build the documentation why should I connect to the Internet and especially don't know what is retrieved / send (this is of course always a concern).

The problems in windows have to do with python usage. As I have a mixed system Windows / Cygwin this gives some problems. I now disabled the cygwin in the path and followed the instructions as provided. the cmake generation looks like not to give the word error anymore. Now building ...

couet commented 3 years ago

@AdvaitDhingra as @albert-github said: that's what I was suggesting . And yes ROOT has to be build. The ROOT-Doxygen filter runs ROOT several hundred of times during the doc build.

albert-github commented 3 years ago

@couet, @bellenot How to build the documentation under windows. The Makefile in documentation/doxygen looks to me like a typical *nix Makefile (and also seen the used commands like ./makehtmlfooter.sh and as I now attempt the Windows version ...

couet commented 3 years ago

@bellenot can confirm but I think we never built the documentation on Windows. We do not really need it. I never do it myself and I do not think he did it either. The documentation is built every night via a jenkins task. For people wanting a local version of the documentation we provide a download page https://root.cern/reference/ . Building the full ROOT documentation is very long... several hours. Nobody does that. Only the developers build some part of it locally . And I do not think any of us does it on Windows.

albert-github commented 3 years ago

Will be a hard task for me than to build and test the documentation.

As a side note did you ever think about using doxygen tag files? A project that extensively uses doxygen tag files for their project is the CGAL project (See https://www.cgal.org/ and https://doc.cgal.org/latest/Manual/packages.html). It is not easy to build and initially it takes also a complete doxygen run (to create a.o. the tag files) but later on it is possible to build individual manuals / subprojects. I don't know how feasible this would be for ROOT though.

bellenot commented 3 years ago

@albert-github sorry, never looked at the documentation building on Windows...

albert-github commented 3 years ago

Building the Windows version:

  Creating directories for 'TBB'
  Building Custom Rule E:/Programs/github_repositories/normal/root/CMakeLists.txt
  Performing download step (download, verify and extract) for 'TBB'
  -- TBB download command succeeded.  See also E:/Programs/github_repositories/normal/root/build_windows/TBB-prefix/src/TBB-stamp/T
  BB-download-*.log
  No update step for 'TBB'
  No patch step for 'TBB'
  Performing configure step for 'TBB'
  CMake Error at E:/Programs/github_repositories/normal/root/build_windows/TBB-prefix/src/TBB-stamp/TBB-configure-Release.cmake:49
  (message):
    Command failed: 1

     'devenv.exe' '/useenv' '/upgrade' 'build/vs2013/makefile.sln'

    See also

      E:/Programs/github_repositories/normal/root/build_windows/TBB-prefix/src/TBB-stamp/TBB-configure-*.log

Might be due to (from the log files):

Microsoft Visual Studio 2019 Version 16.9.4.
Copyright (C) Microsoft Corp. All rights reserved.

The license for Visual Studio has expired.

The evaluation period for this product has ended.

bellenot commented 3 years ago

Well, yes, you need a proper license (free for the academic/open source version)

albert-github commented 3 years ago

The TBB directory comes apparently from http://threadingbuildingblocks.org wanted confirmation by means of a telephone number.

Wouldn't it anyway be good to provide http://threadingbuildingblocks.org and on my build directory I see down in the tar file in TBB-prefix that there is a vs2013 directory and nothing newer. So I probably have to see what I can do with the license without providing telephone numbers and alike ...

Just as a side note: On the page: https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-threading-building-blocks-system-requirements.html I see that there are newer (source) versions which also support: Microsoft Visual C++ 14.2 (Microsoft Visual Studio 2019, Windows OS only) so maybe there is a distribution yjat you could use as well.

bellenot commented 3 years ago

You can simply disable imt (-Dimt=OFF) and builtin_tbb (-Dbuiltin_tbb=OFF).

albert-github commented 3 years ago

@bellenot Thanks, I'm now trying it (runs already again for a while).

Are there more of these high level options and are they documented somewhere? I ran cmake -LA and see a long list, with of course also settings from the subpackages used, but I think the bottom part gives, probably, the list:

alien:BOOL=OFF
all:BOOL=OFF
arrow:BOOL=OFF
asan:BOOL=OFF
asimage:BOOL=ON
asserts:BOOL=OFF
builtin_afterimage:BOOL=ON
builtin_cfitsio:BOOL=OFF
builtin_clang:BOOL=ON
builtin_cling:BOOL=ON
builtin_davix:BOOL=OFF
builtin_fftw3:BOOL=OFF
builtin_freetype:BOOL=ON
builtin_ftgl:BOOL=ON
builtin_gl2ps:BOOL=ON
builtin_glew:BOOL=ON
builtin_gsl:BOOL=OFF
builtin_llvm:BOOL=ON
builtin_lz4:BOOL=ON
builtin_lzma:BOOL=ON
builtin_nlohmannjson:BOOL=ON
builtin_openssl:BOOL=OFF
builtin_openui5:BOOL=ON
builtin_pcre:BOOL=ON
builtin_tbb:BOOL=OFF
builtin_unuran:BOOL=OFF
builtin_vc:BOOL=OFF
builtin_vdt:BOOL=OFF
builtin_veccore:BOOL=OFF
builtin_xrootd:BOOL=OFF
builtin_xxhash:BOOL=ON
builtin_zlib:BOOL=ON
builtin_zstd:BOOL=ON
ccache:BOOL=OFF
cefweb:BOOL=OFF
clad:BOOL=ON
clingtest:BOOL=OFF
cocoa:BOOL=OFF
compression_default:STRING=zlib
coverage:BOOL=OFF
cuda:BOOL=OFF
cudnn:BOOL=ON
cxxmodules:BOOL=OFF
daos:BOOL=OFF
dataframe:BOOL=ON
davix:BOOL=OFF
dcache:BOOL=OFF
dev:BOOL=OFF
distcc:BOOL=OFF
exceptions:BOOL=ON
fail-on-missing:BOOL=OFF
fcgi:BOOL=OFF
fftw3:BOOL=OFF
fitsio:BOOL=OFF
fortran:BOOL=OFF
gcctoolchain:PATH=
gdml:BOOL=ON
gfal:BOOL=OFF
gminimal:BOOL=OFF
gnuinstall:BOOL=OFF
gsl_shared:BOOL=OFF
gviz:BOOL=OFF
http:BOOL=ON
imt:BOOL=OFF
jemalloc:BOOL=OFF
libcxx:BOOL=OFF
macos_native:BOOL=OFF
mathmore:BOOL=OFF
memory_termination:BOOL=OFF
minimal:BOOL=OFF
minuit2:BOOL=ON
minuit2_mpi:BOOL=OFF
minuit2_omp:BOOL=OFF
mlp:BOOL=ON
monalisa:BOOL=OFF
mpi:BOOL=OFF
mysql:BOOL=OFF
nlohmann_json_DIR:PATH=nlohmann_json_DIR-NOTFOUND
odbc:BOOL=OFF
opengl:BOOL=ON
oracle:BOOL=OFF
pgsql:BOOL=OFF
pyroot:BOOL=OFF
pyroot_legacy:BOOL=OFF
pythia6:BOOL=OFF
pythia6_nolink:BOOL=OFF
pythia8:BOOL=OFF
qt5web:BOOL=OFF
r:BOOL=OFF
roofit:BOOL=ON
root7:BOOL=OFF
rootbench:BOOL=OFF
roottest:BOOL=OFF
rpath:BOOL=OFF
runtime_cxxmodules:BOOL=OFF
shadowpw:BOOL=OFF
shared:BOOL=ON
soversion:BOOL=OFF
spectrum:BOOL=ON
sqlite:BOOL=OFF
ssl:BOOL=OFF
tcmalloc:BOOL=OFF
test_distrdf_pyspark:BOOL=OFF
testing:BOOL=OFF
tmva:BOOL=ON
tmva-cpu:BOOL=OFF
tmva-gpu:BOOL=OFF
tmva-pymva:BOOL=OFF
tmva-rmva:BOOL=OFF
tmva-sofie:BOOL=OFF
unuran:BOOL=OFF
uring:BOOL=OFF
vc:BOOL=OFF
vdt:BOOL=OFF
veccore:BOOL=OFF
vecgeom:BOOL=OFF
webgui:BOOL=OFF
win_broken_tests:BOOL=OFF
winrtdebug:BOOL=OFF
x11:BOOL=OFF
xml:BOOL=OFF
xproofd:BOOL=OFF
xrootd:BOOL=OFF
xxHash_FOUND:BOOL=TRUE

Edit: compilation build finished now without errors.

bellenot commented 3 years ago

Are there more of these high level options and are they documented somewhere?

Some of them are. See https://root.cern/install/build_from_source/

albert-github commented 3 years ago

@bellenot Thanks I found them under the header "All build options" (https://root.cern/install/build_from_source/#all-build-options) and here are 2 versions one for version 6.22 and 6.24.

(One of my next steps will be to try to build the documentation under Windows ..., though will take a while before I can start with this)

bellenot commented 3 years ago

One of my next steps will be to try to build the documentation under Windows ..., though will take a while before I can start with this

I never tried this. Good luck!

couet commented 3 years ago

As a side note did you ever think about using doxygen tag files?

ROOT documentation is included in many experiments' documentations. We provide the tag files for them . The page files can be downloaded (for various versions of the documentation) from this page.

albert-github commented 3 years ago

@couet That is a nice service to the users. I was thinking about the usage of tag files for "internal" use where the build of the documentation would be split in different parts ("sub-projects") so that each part generates its own tag file that can be used by the other sub-projects. This could make the building of the documentation a bit more modular and it would give the opportunity to re-build just one sub-project (could be useful during development). I don't know how feasible this would be for the ROOT project though.

couet commented 3 years ago

@albert-github That's a nice idea, and could be something to think about. I think we will anyway to build the whole documentation every night because:

the various modules refer to each other a lot,
we want to run all the code available in the doc. We have test suites to validate de software but the documentation is surely an extra one.
- now it takes "only" a night so it is still doable to build it daily. If at some point the building becomes unmanageable the approach you suggest might be a solution.

albert-github commented 3 years ago

The complete overnight build is certainly necessary and preferably from scratch (so no residuals are left over). Advantage of the tag files might be that some sub-projects can be build in parallel. A reasonable new feature is the setting NUM_PROC_THREADS, so it might still be a bit buggy but it would definitely be of interest to see how ROOT performs here and whether or not the output is the same for larger project, so doxygen could be improved as well.

couet commented 3 years ago

I guess this one can be closed now.

github-actions[bot] commented 3 years ago

Hi @couet, @bellenot,

It appears this issue is closed, but wasn't yet added to a project. Please add upcoming versions that will include the fix, or 'not applicable' otherwise.

Sincerely, :robot:

root-project / root

How to build just the documentation #8742