1. 16 Oct, 2013 12 commits
    • 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
  2. 15 Oct, 2013 28 commits