Add ENABLE_DOCS to CMake

Create issue
Issue #9 wontfix
David Williams created an issue

CMake exposes a number of properties at configuration time such as ENABLE_BINDINGS, etc. It would be nice to be able to disable building the documentation as wll as it takes some time and happens whenever I modify a source file.

Comments (12)

  1. Matt Williams

    The doc target should only be built when explicitly asked. On Linux this means that a simple make will not build the Doxygen docs but a make doc or make manual will. What is the target that you build?

  2. David Williams reporter

    In Visual Studio you can build the whole solution or you can build individual projects. If you build the whole solution then it builds all projects including the documentation. If you build a particular project then it only builds the projects on which your selected project depends.

    So if you do 'Build->Build Solution' then it does indeed build the documentation project. Sounds like this is different to Linux.

    Edit: I should also point out that I usually just build solution rather than individual projects because there is a keyboard shortcut for this :-)

    An extra complication is that the doc building process never completes sucessfully due to the error we discussed previously ('Encountered incorrectly encoded content.'). This means it's also building the documentation when nothing has changed, as the documentation never gets up to date.

  3. Matt Williams

    There should be an ALL_BUILD target available which should do the equivalent of make and should not build the Doxygen docs. If this works, it should be possible for you to set ALL_BUILD to be the default target.

    If this does not work then I can add an ENABLE_DOCS (and maybe 'manual'?) option to disable them.

  4. David Williams reporter

    The ALL_BUILD target does indeed behave as you describe. However, there doesn't appear to be a keyboard shortcut to build a given project. I found a macro which builds the startup project (the one which gets run when you press F5) so maybe this can be modified... but of course the one I want to buld (ALL_BUILD) is not the one I want to run (BasicExample, for example).

    I think the ENABLE_DOCS would be useful. I don't want to pile work on you so I don't mind adding it myself... I assume it's a simple logical extension of the other ENABLE_XXX flags?

  5. Matt Williams
    • changed version to 0.3

    Ok. MSVC is obviously different enough to make that it's potentially causing problems. I will add an ENABLE_DOCS for version 0.3.

  6. David Williams reporter

    Ok, sounds good. There's no urgency - I've been getting around it by just renaming my Doxygen and Sphinx folders so they are not found by CMake.

  7. David Williams reporter
    • removed assignee

    Hmmm... actually I'm not sure I know enough about CMake to do this. The Sphinx stuff in particular is a little difficult for me.

    Do you think we need to clarify the term 'documentation'? It seems that with in the CMake stuff it refers specifically to the API reference, whereas an 'ENABLE_DOCS' option should probably refer to both reference and manual? Unless you think it is useful to be able to enable/disable them individually?

    I guess we need:

    BUILD_REFS

    BUILD_AND_BUNDLE_REFS (or just BUNDLE_REFS?)

    BUILD_MANUAL

    And they should all be controlled by a gobal ENABLE_DOCS?

    I'm unassigning myself again because it turns out it's too painful to work on this from my laptop as CMake runs rather slowly. I'm off to England for a few days but will have another look when I'm back at home/work at the end of next week.

  8. David Williams reporter

    I think we can probably just let this go - I was probably being too pedantic about trying to get Visual Studio to behave exactly the way I'm used to. Some things are going to be different when working through CMake, and overall it's an excellent system where the benefits of cross platform support outweigh the minor annoyances of some things being slightly different.

    That said, I'll have a quick review of the CMake scripts before the 0.3 release to make sure that it all still works as expected on Windows.

  9. Log in to comment