1. 16 Oct, 2013 22 commits
    • Brad King's avatar
      Help: De-duplicate manual/(cmake|ccmake).1.rst build options · 5dde65ac
      Brad King authored
      Move common build options out of cmake and ccmake manuals into an
      OPTIONS_BUILD.txt file and include it from the original locations.
      5dde65ac
    • Brad King's avatar
      Help: Organize manual/*.1.rst sections · ae944d17
      Brad King authored
      Add "Synopsis", "Description", and "See Also" manual page section
      headers.  These are typical of .1 man section pages.  Also de-duplicate
      the See Also section links using a separate LINKS.txt file included from
      each manual.
      ae944d17
    • Brad King's avatar
      Help: Drop leftover conversion content from manual/*.1.rst · 4f7d708a
      Brad King authored
      Some text in these manuals is left from the old full help transition
      text generated by the automatic conversion process.  Drop it.
      4f7d708a
    • Brad King's avatar
      Merge topic 'update-kwsys' · c54fb6fe
      Brad King authored
      0408415b Merge branch 'upstream-kwsys' into update-kwsys
      c01e7445 KWSys 2013-10-15 (6eab64c3)
      c54fb6fe
    • Brad King's avatar
      Merge topic 'doc-reStructuredText' · c49083e9
      Brad King authored
      7038a93a Modules/readme.txt: Update steps to add module documentation
      a77e3086 CPack: Replace #<type> markup with reStructuredText equivalent
      e7ca48f2 Help: Factor out cmake-generator-expressions manual page
      97e8650d Help: Factor out COMPILE_DEFINITIONS disclaimer duplication
      89821613 Help: Factor out find_* command duplication
      30b21860 Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication
      bfe07aa9 Build Help documentation during CMake build using Sphinx
      53ded595 Drop unused builtin documentation APIs
      0c39a757 Drop the 'Full' field from cmDocumentationEntry
      e33d8d2d Drop builtin command documentation
      399e9c46 Drop builtin property documentation
      6035c045 get_property: Drop test for builtin property documentation
      80a3273b Drop all documentation formatters except Usage
      b336a1eb Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents
      ec6df367 Teach --help-* options to load documentation from .rst files
      25f2877e Add class cmRST to do basic reStructuredText processing
      ...
      c49083e9
    • Brad King's avatar
      Modules/readme.txt: Update steps to add module documentation · 7038a93a
      Brad King authored
      Replace the old module documentation instructions with steps to add
      reStructuredText documentation that will be built by Sphinx.
      7038a93a
    • Kitware Robot's avatar
      CPack: Replace #<type> markup with reStructuredText equivalent · a77e3086
      Kitware Robot authored
      Drop #end and #module.  Convert #section to a subsection header.
      Convert #variable to the cmake domain "variable" directive.
      Convert #macro to the cmake domain "command" directive.
      Perform minor formatting fixes in text near these changes.
      a77e3086
    • Brad King's avatar
      Help: Factor out cmake-generator-expressions manual page · e7ca48f2
      Brad King authored
      Generator expressions are supported in many places and are a distinct
      concept worthy of their own manual page.  The old builtin documentation
      was previously represented by preprocessor macros to generate it into
      each place that supports them.  Factor out the duplicate content into a
      dedicated cmake-generator-expressions manual page and reference it from
      each original location.
      e7ca48f2
    • Brad King's avatar
      Help: Factor out COMPILE_DEFINITIONS disclaimer duplication · 97e8650d
      Brad King authored
      The COMPILE_DEFINITIONS escaping disclaimer was represented in builtin
      documentation using a preprocessor macro.  Factor the duplicate content
      out into a separate .txt file and include it in each document with the
      reStructuredText include directive.
      97e8650d
    • Brad King's avatar
      Help: Factor out find_* command duplication · 89821613
      Brad King authored
      These documents were represented in the builtin documentation using a
      common starting point with placeholders substituted by each command.
      Convert them back to this approach using the reStructuredText include
      directive and substitutions to avoid duplication.
      89821613
    • Brad King's avatar
      Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication · 30b21860
      Brad King authored
      Portions of these documents contain duplicate content generated from
      preprocessor macros in the original builtin documentation source.
      Factor the common parts out into .txt files using reStructuredText
      include directives and substitutions to avoid duplication.
      30b21860
    • Brad King's avatar
      Build Help documentation during CMake build using Sphinx · bfe07aa9
      Brad King authored
      Add a Utilities/Sphinx directory to hold CMake build code to run the
      Sphinx (sphinx-doc.org) documentation generation tool.  Create a
      CMakeLists.txt file there capable of building either as a subdirectory
      of the main CMake build, or as a standalone documentation build.
      
      Add cache options SPHINX_MAN and SPHINX_HTML to select output formats
      and SPHINX_EXECUTABLE to specify the sphinx-build executable.  Add
      bootstrap options --sphix-man and --sphinx-html to select output formats
      and --sphinx-build=<sb> to specify the sphinx-build executable.
      
      Create a "conf.py.in" file to configure_file into "conf.py" to tell
      sphinx-build how to build our documents.  Create a "cmake.py" Sphinx
      extension module defining:
      
      * The "cmake-module" directive used in Help/module/*.rst files to
        scan .rst markup from the corresponding Modules/*.cmake file.
      
      * A Sphinx domain called "cmake" defining documentation object types
        for CMake Help/<type> directories: command, generator, manual,
        module, policy, prop_*, and variable.  Add a "role" for each type
        to perform cross-references.  Teach the roles to treat "<XYZ>"
        as placeholders instead of explicit targets if not preceded by
        a space.  Add cmake domain directives to define command and
        variable objects explicitly in .rst file content.  This will
        allow modules to define their own commands and variables and
        have them indexed and linkable.
      
      * A Sphinx document transform that converts Help/<type>/*.rst documents
        into cmake domain objects of the corresponding <type> and adds index
        entries for them.  This will automatically index all CMake documentation
        objects and provide cross-reference targets for them with no special
        markup in the .rst files.
      bfe07aa9
    • Brad King's avatar
      Drop unused builtin documentation APIs · 53ded595
      Brad King authored
      Now that all DefineProperty documentation calls have been dropped, drop
      the supporting APIs.
      53ded595
    • Brad King's avatar
      Drop the 'Full' field from cmDocumentationEntry · 0c39a757
      Brad King authored
      We need only 'Brief' for usage documentation.  We no longer have builtin
      'Full' documentation, which is now in Help/*/*.rst files.
      0c39a757
    • Brad King's avatar
      Drop builtin command documentation · e33d8d2d
      Brad King authored
      Drop all GetTerseDocumentation and GetFullDocumentation methods from
      commands.  The command documentation is now in Help/command/*.rst files.
      e33d8d2d
    • Brad King's avatar
      Drop builtin property documentation · 399e9c46
      Brad King authored
      Drop all DefineProperty calls for non-chained properties.  Drop the
      documentation from the chained ones.  The documentation for all
      properties is now in Help/prop_*/*.rst files.
      399e9c46
    • Brad King's avatar
      get_property: Drop test for builtin property documentation · 6035c045
      Brad King authored
      Property documentation is no longer builtin, so the get_property command
      will be unable to return the documentation.  Drop the test for it.
      6035c045
    • Brad King's avatar
      Drop all documentation formatters except Usage · 80a3273b
      Brad King authored
      We now need only the Usage formatter to support command-line options
      that print basic usage, and the supporting indented=>preformatted markup
      processor to support CMake message formatting.  Drop all other
      documentation formatters and move the remaining code up into the top
      cmDocumentationFormatter class.
      80a3273b
    • Brad King's avatar
      Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents · b336a1eb
      Brad King authored
      These checks want to know if named target properties are builtin, which
      is now known by checking the Help/prop_tgt directory.  (Previously the
      check could be confused by a define_property call in the project.)
      b336a1eb
    • Brad King's avatar
      Teach --help-* options to load documentation from .rst files · ec6df367
      Brad King authored
      Install the Help directory next to Modules to make it available in CMake
      distributions.  Use cmRST to read Help .rst documents and print them as
      help output.
      
      Add options
      
       --help-manual-list
       --help-manual
      
      to list available manuals or print one of them.  Implement the options
      
       --help-commands
       --help-modules
       --help-policies
       --help-properties
       --help-variables
      
      by mapping to the corresponding manual page.  Implement the options
      
       --help-command-list
       --help-module-list
       --help-policy-list
       --help-property-list
       --help-variable-list
      
      by globbing the available Help .rst documents of the corresponding type
      and reading their titles.  Implement the options
      
       --help-command
       --help-module
       --help-policy
       --help-property
       --help-variable
      
      by globbing the matching Help .rst document(s) and printing them.
      ec6df367
    • Brad King's avatar
      Add class cmRST to do basic reStructuredText processing · 25f2877e
      Brad King authored
      Create a cmRST class to perform just enough reStructuredText processing
      to support display of Help documents in human-readable text format.
      This will be used to implement --help-* command-line options.
      
      Support directives "include", "replace", "parsed-literal", "toctree"
      (Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
      modules).  Support inline CMake Sphinx Domain roles to convert
      cross-references to corresponding title text.  Support inline
      substitutions defined by the "replace" directive, but keep it simple by
      requiring replacements to be defined before use.
      
      Add a CMakeLib "testRST" case to cover processing of supported
      constructs and compare results against expected output.
      25f2877e
    • Kitware Robot's avatar
      CMake Nightly Date Stamp · 5029da5e
      Kitware Robot authored
      5029da5e
  2. 15 Oct, 2013 18 commits
    • Brad King's avatar
      Drop "full" documentation output types · 87cc62ca
      Brad King authored
      We will no longer support full documentation generation from executables
      and will instead generate documentation with other tools.  Disable (with
      a warning left behind) the command-line options:
      
       --copyright
       --help-compatcommands
       --help-full
       --help-html
       --help-man
      
      Drop supporting code.  Drop manual sections generation from executables.
      Remove internal documentation construction APIs.  Drop unused sections
      See Also, Author, Copyright, Compat Commands, Custom Modules.
      87cc62ca
    • Brad King's avatar
    • Brad King's avatar
      Help: Add index.rst top-level document · 6ceb6511
      Brad King authored
      Add a top-level document holding the Sphinx root toctree.  List all
      reference manuals from Help/manual/*.rst and the Sphinx-generated
      general index (genindex) and search pages.
      6ceb6511
    • Brad King's avatar
      ExternalProject: Restore documentation indentation level · c717e2aa
      Brad King authored
      This module parses its own documentation to extract supported options.
      Fix the indentation level to match that expected by the parser.
      c717e2aa
    • Kitware Robot's avatar
      Convert builtin help to reStructuredText source files · f051814e
      Kitware Robot authored
      Run the convert-help.bash script to convert documentation:
      
       ./convert-help.bash "/path/to/CMake-build/bin"
      
      Then remove it.
      f051814e
    • Brad King's avatar
      Add bash script to convert builtin help to reStructuredText · e94958e9
      Brad King authored
      Create a convert-help.bash script to extract builtin documentation as
      reStructuredText sources in a new Help directory.  Run each executable
      with the --help-full option targeting a .rst file to extract the
      documentation.  Generate Sphinx "toctree" directives to point each man
      page at the corresponding documents it should contain.  Organize
      cmake-commands(7), cmake-properties(7), and cmake-variables(7) man pages
      into sections similar to those generated by --help-properties and
      --help-variables output previously.
      e94958e9
    • Kitware Robot's avatar
      Add Help/generator/*.rst for Windows- and OS X-only generators · 81759c77
      Kitware Robot authored
      Run "cmake --help-full cmake.1.rst" by hand on Windows and OS X.
      Copy the generator/*.rst documents for generators unique to those
      platforms into Help/generator.
      81759c77
    • Brad King's avatar
      Add reStructuredText (RST) documentation formatter · f85405f5
      Brad King authored
      Temporarily add a RST formatter to convert builtin documentation to .rst
      source files.  This will be removed shortly after we use it to convert
      documentation.
      
      Teach the RST formatter to:
      
      * Output preformatted blocks as reStructuredText "::" literal blocks.
      
      * Output option lists as bullet lists with option names enclosed in
        reStructuredText ``literal`` quoting.
      
      * Output individual documentation objects (commands, variables, etc.)
        in separate .rst files organized in directories by type.
      
      Replace references to cmVersion::GetCMakeVersion() in builtin
      documentation with the literal placeholder "|release|" that will be
      defined as a substitution later.
      f85405f5
    • Brad King's avatar
      Drop CPack module documentation markup extraction · 0d0fec15
      Brad King authored
      This will be replaced by alternative markup later.
      0d0fec15
    • Brad King's avatar
      Drop definition of internal property · 946f0efb
      Brad King authored
      The property __CMAKE_DELETE_CACHE_CHANGE_VARS_ is not meant for public
      exposure.
      946f0efb
    • Brad King's avatar
      Drop CMAKE_STRICT mode · 277bd1db
      Brad King authored
      With our modern development workflow it is less likely a property will
      be added to C++ code without documentation.  This mode only existed to
      support the DocTest which had very limited coverage of the properties
      anyway.
      277bd1db
    • Brad King's avatar
      Drop documentation generation during build · 678aaad1
      Brad King authored
      Drop the 'documentation' build target.  We will no longer use the
      executables to generate their own documentation.  New infrastructure
      will be introduced later to generate documentation.
      678aaad1
    • Brad King's avatar
      Set IDE folder for CMake 'documentation' target only if it exists · 09be0bb0
      Brad King authored
      The documentation target will be come optional, so do not reference it
      when it does not exist.
      09be0bb0
    • Brad King's avatar
      Drop xmllint documentation tests · e49efe91
      Brad King authored
      Drop these tests since we will drop docbook output along with other
      documentation formatters.
      e49efe91
    • Brad King's avatar
      Move cmake.m4 from Utilities to Auxiliary · 189008ea
      Brad King authored
      The latter fits more consistently with other third party integration
      files.
      189008ea
    • Brad King's avatar
      Rename Docs to Auxiliary · b601e235
      Brad King authored
      The directory contains auxiliary support files for integration with
      other tools, not documentation.
      b601e235
    • Brad King's avatar
      cmDocumentation: Drop version output from usage and text help · 07b80021
      Brad King authored
      Drop the "cmake version ..." line from the top of usage and text help
      formats.  Print it only when requested with --version or similar option.
      07b80021
    • Brad King's avatar
      cmake: Add --help-policy-list option · 6e68bc22
      Brad King authored
      All the other --help-<item> options have a corresponding option
      --help-<item>-list.  Add one for --help-policy.
      6e68bc22