Sort out and document CMake targets

[jougs]

We currently have a bunch of different make targets, which are partly the result of a) using CMake defaults, b) carrying over defaults from the time when the build system still used autotools, and c) custom targets (some of which have bad names for historic reasons).

Current situation

all

• compile all source files and link static and dynamic libraries, as well as the executables
• cythonize PyNEST and compile it;

install

• run the SLI help extractor

install everything to directories under the <nest_install_dir>

• SLI standard library, SLI examples, extracted SLI help files
• dynamic libraries, executables (nest, sli) and helpers (nest-config, nest-vars.sh)
• PyNEST and its examples
• the testsuite

install-nodoc

• same as install, but without running the SLI help extractor

installcheck

run the testsuite (essentially by calling do_tests.sh) using the installed executables and the test files from <nest_install_dir>/share/doc/nest

doc and fulldoc

run Doxygen to extract the C++-level user documentation in either

• a minimal configuration (doc), or in
• a extended configuration (fulldoc) including class inheritance diagrams and all bling.

html

run the Sphinx-based user-level documentation generation pipeline. This also runs the doc extractor that gets the model documentation snippets from the C++ files that implement them.

Proposal

There is some (well justified) confusion between what these targets actually do. A proposal for a more sane naming and task split would probably be

• all can stay
• install would do the same as before minus running the doc-extractor
• userdoc would do what html currently does, plus run the SLI doc extractor
• devdoc would do what fulldoc currently does
• install-userdoc would install what userdoc has produced
• install-devdoc would install what devdoc has produced

This issue is also related to #291.

[heplesser]

I like your proposal. But I wonder if we need separate build and install targets for documentation? How about just having the install-{user,dev}doc targets?

The distinction between doc and fulldoc was introduced once upon a time because creating "all the bling" just took forever. Might want to check how long it takes today ...

[jougs]

Here are some additional observations that result from a video call with @heplesser:

• we indeed only want a single target for generating the developer documentation and that should be as rich as possible (i.e. run Doxygen in full-on configuration)
• we actually should not have separate targets for installing the documentation. make install should just install whatever has been built before running it
• in summary this means we should go for
  • all: build static and dynamic libraries; compile and link executables; cythonize and compile PyNEST
  • userdoc: extract SLI help, model documentation, PyNEST command index and run the Sphinx pipeline
  • devdoc: run Sphinx to generate an landing page; extract Doxygen comments using Doxygen or Breathe
  • install: install everything that was build in prior steps.

[jougs]

There seems to be a bit of confusion about the fact that no user documentation is available after make install if you did not also call make html before that. Here's a new proposal that should reduce the potential for confusion and also takes in some input I gathered in various video calls over the past weeks:

• all: build static and dynamic libraries; compile and link executables; cythonize and compile PyNEST
• userdoc: extract SLI help, model documentation, PyNEST command index and run the Sphinx pipeline
• devdoc run Doxygen to extract the class and function information, but also general help texts available in Doxygen format
• install: depend on all and userdoc and install executables, libraries and user documentation, as well as - if built beforehand - developer documentation; this assumes that compilation is the default task for normal users and a one-time operation that might as well be a bit more costly
• install-nobuild same as install but without any dependencies on other targets; allows for quicker compile-install-cycles, when documentation is not the main focus of the development (make all install-nobuild); only installs artifacts from previous runs of make using the all, userdoc, or devdoc targets.

[heplesser]

@jougs With the targets you propose, the typical approach for a developer who want to compile, install and test, ignoring anything to do with documentation, would then be

make all && make install-nobuild && make installcheck

Correct? I think this makes sense and keeps the number of different targets in bounds.

[terhorstd]

So the all target does not do everything? Should we rename the target to something more reasonable, then? Also the install-nobuild target is very confusing to me. This is all working against the concepts of make that would always try to work through all prerequisites of the target rules. I'd suggest a configure flag for cmake "-Dwith-userdoc", "-Dwith-devdoc", and no separate make targets.

[heplesser]

all builds all the executable material, which is what I would expect of all. Documentation is something additional. So I think keeping all is fine.

[gtrensch]

Isn't it the case that documentation is part of our source code and we should therefore treat it like a normal module? Assuming there is an agreement on that, wouldn't it makes perfect sense to control the doc build process by using CMake variables? Using CMake variables to configure the doc build would simplify the make process and create more clarity. It furthermore could be a good solution for #1775.

[terhorstd]

@jougs, @gtrensch, is someone looking into this at the moment?

[jougs]

I'm not and I'm not aware of anyone else doing this.

[terhorstd]

This is partially already modified with #1959, which should be seen in this context.

[gtrensch]

Summary of the decision made at the last hackathon:

• Move documentation Make build options to CMake variables to unify build configuration
• Introduce new CMake variables user-doc and dev-doc providing the following options
  user-doc = on/off, Default: user-doc = on
dev-doc = on/off/full, Default: dev-doc = off, dev-doc = on only builds doxygen doc without class diagrams.

[github-actions]

Issue automatically marked stale!

[Helveg]

A "lean" superflag would also be appreciated: no share, no docs, no test, no help, no cruft. Just the binaries and libs 👍