Commit Graph

40 Commits

Author SHA1 Message Date
Brad King 8235effe48 Help: Drop FeatureSummary example in cmake-developer.7
The use of FeatureSummary inside a find module is not a convention
yet used by upstream CMake modules.  Drop the example from the
documentation about how to write find modules.  If in the future
we add use of FeatureSummary to many of the upstream find modules
then this example can be restored as part of establishing the
convention.
2014-12-09 08:40:17 -05:00
Stephen Kelly 67cb50abd7 Help: Document that IMPORTED targets in Find modules may be UNKNOWN. 2014-12-05 00:12:14 +01:00
Stephen Kelly e18e21aeb5 Help: Document IMPORTED_CONFIGURATIONS target property for Find modules. 2014-12-05 00:12:14 +01:00
Stephen Kelly f0d0d761b2 Help: Remove recommendation about checking minimum CMake version.
If this file is being executed, the user has the CMake version
providing it.
2014-12-04 23:55:15 +01:00
Stephen Kelly 31452416ba Help: Add useful links to IMPORTED targets and usage requirements. 2014-12-04 23:33:50 +01:00
Stephen Kelly b96b025b2a Help: Remove disadvantage creating IMPORTED targets in Find modules.
An IMPORTED target in either type of package can equally depend on
an IMPORTED target in a Find module, which must be found as a
dependency, which is presumably the problem being implied.  This is
not a distinction of creating an IMPORTED target in a Find module.
2014-12-04 23:32:52 +01:00
Stephen Kelly 169f116632 Help: Link to cmake-packages(7) from the Module creation documentation. 2014-12-04 23:31:59 +01:00
Stephen Kelly beaea609a0 Remove note disallowing use of some string and vector API.
The compilers introducing these limitations are no longer supported
as host compilers.
2014-11-25 18:35:00 +01:00
Stephen Kelly c2af447d44 Remove disallowed feature which Borland did not accept. 2014-11-25 10:34:47 -05:00
Stephen Kelly 12cb0b868c Help: Update developer manual with some C++ features now permitted. 2014-11-20 23:11:38 +01:00
Brad King a9dcf4773c Help: Drop TOC from latex manuals
A latex document can have its own TOC.
2014-11-06 14:46:18 -05:00
Brad King 80b19a7127 Help/manual: Avoid long lines in code blocks
Update the wording of some examples to avoid long lines in code blocks.
Otherwise the formatted documentation can exceed certain column width
limitations.
2014-10-22 16:48:04 -04:00
Robert Maynard cff33e03e9 Help: Clarify size_t usage in cmake-developer.7 2014-10-03 15:09:30 -04:00
Brad King d8319f0fc9 Help: Update style guide to use section headers for command signatures
In order to be able to link to specific command signatures we need to
use a section header instead of a horizontal separator.
2014-06-12 13:57:36 -04:00
Brad King 793b64e499 Help: Document section header underline hierarchy in cmake-developer.7
Explicitly specify the sequence of underline characters we use in the
CMake documentation.  It is the same sequence as that suggested in the
Sphinx documentation, but we have our own descriptions.
2014-06-02 14:04:00 -04:00
Brad King 05bd31ab3e Help: Organize documentation style sections in cmake-developer.7
Now that the style guidelines have section titles instead of numbers,
organize them into more well-defined sections.
2014-06-02 14:02:47 -04:00
Brad King eaafe756d5 Help: Add documentation style section headers to cmake-developer.7
Give the style guides titles instead of numbers so we can link to them.
2014-06-02 14:01:24 -04:00
Brad King 4207b3a3bb Help: Use "^^^^" for subsubsection headers
This is the convention suggested in the Sphinx documentation and is
already used in several other places in the CMake documentation.
Update a few places where we were using other characters.
2014-06-02 14:00:33 -04:00
Brad King 8df4d03d99 Merge topic 'cpack-properties'
d0b1d2a6 CPackWiX: Implement CPACK_NEVER_OVERWRITE and CPACK_PERMANENT properties
15a8af21 Add an "installed file" property scope
2014-05-28 12:34:36 -04:00
Nils Gladitz 15a8af21e8 Add an "installed file" property scope
Teach set_property and get_property an "INSTALL" property type to be
associated with install-tree file paths.  Make the properties available
to CPack for use during packaging.  Add a "prop_inst" Sphinx domain
object type for documentation of such properties.
2014-05-28 12:28:18 -04:00
Stephen Kelly ca5d990f02 Help: Add a manual for compiler feature control.
Link to it from the documentation of related properties, variables
and commands.

Extend the cmake-developer(7) documentation with notes on
extending feature support for compilers.
2014-05-27 09:35:00 -04:00
Alex Merry fcdf86d004 Help: Rewrite the cmake-developer.7 find module documentation
As well as the traditional variables, providing imported targets is
suggested, and the relative advantages and disadvantages briefly
discussed.

A mini-tutorial walking through creating a simple find module is
provided.

This changes the recommended version variable from Foo_VERSION_STRING to
Foo_VERSION, because there is really no need to have different variable
names for package version files vs. find modules.  It notes the old
variable name, though, and suggests setting it for compatibility.
2014-04-02 10:59:29 -04:00
Brad King 328c217960 Help: Drop cmStdString from cmake-developer(7) examples
The type no longer exists within CMake.
2014-03-13 15:11:22 -04:00
Stephen Kelly a74d125a7c Help: Fix typo
binary_find -> binary_search.
2014-02-17 11:07:59 +01:00
Stephen Kelly 6c02e7f427 Help: Add a style guide. 2014-02-06 16:15:50 -05:00
Stephen Kelly 91fbff8820 Help: Fix typos
Psuedo -> Pseudo

 behaviour -> behavior

CMake uses American spelling.
2014-02-06 16:14:13 -05:00
Stephen Kelly ed632736e3 Help: Note that std::string::clear may not be used.
As found in commit 519c0a5d (Can't use std::string::clear() in
cmake., 2012-09-15).
2014-01-27 13:02:59 -05:00
Stephen Kelly cc04bb6c16 Help: Document non-use of std::set::insert.
As found in commit 8e7c207e (Use a manual loop to insert into
set::set., 2012-09-15).
2014-01-27 13:02:59 -05:00
Stephen Kelly 58c174e945 Help: Document the C++ subset permitted for CMake code.
This may be incomplete, but further limitations can be added when
needed.
2014-01-06 19:15:31 +01:00
Brad King 79fd233806 Help: Reference cmake-language.7 comment docs from cmake-developer.7
The cmake-language.7 manual now documents comment syntax.  Reference it
from cmake-developer.7 when discussing how to add comment-enclosed
documentation to modules.
2013-11-08 08:41:49 -05:00
Brad King 450b515ad0 cmRST: Add support for the note and productionlist directives
Simply print out the lines as normal paragraph text.  Teach the
CMakeLib.testRST test to cover this syntax.  Update the
cmake-developer.7 manual to document support for the directives.
2013-10-30 10:26:29 -04:00
Brad King f88332f5b7 Help: Glob manual/*.rst in Sphinx configuration
Add the man page description line as explicit markup at the top of each
Help/manual/*.rst file and scan it from conf.py to automatically
generate the man_pages Sphinx configuration value.  This reduces the
number of places that need to be changed when a new manual is added.
2013-10-30 09:58:25 -04:00
Brad King 2945814de2 cmRST: Teach cmake-module directive to scan bracket comments
When scanning CMake module files for .rst comments, recognize
bracket comments starting in ".rst:" too.  For example:

 #[[.rst:

Include the bracket comment content terminated by the closing bracket.
Exclude the line containing the bracket if it starts in "#".

Teach the CMakeLib.testRST test to cover multiple bracket lengths
and ending brackets on lines with and without "#".

Update the cmake-developer.7 manual to document the bracket-comment
syntax for .rst documentation.
2013-10-23 09:36:00 -04:00
Brad King 8bb2ee96cc cmake-developer.7: Improve flow of module documentation instructions
Use prose instead of enumerated steps and re-order the steps so that
the cmake-module directive is covered contiguously.
2013-10-23 09:36:00 -04:00
Brad King e0ce6f0a22 cmRST: Cross-reference cmake-developer.7 manual and cmRST Doxygen
The cmRST implementation and the list of capabilities documented in the
cmake-developer.7 manual must be kept in sync.  Add a note to each file
to reference the other.
2013-10-22 10:55:23 -04:00
Brad King c1c239bf75 Help: Add documentation format to cmake-developer.7 manual
Document how CMake uses reStructuredText to provide the help manuals.
Cover supported inline markup and directives, the CMake Domain in
Sphinx, and cross-reference syntax.
2013-10-22 10:55:23 -04:00
Brad King a06a90f457 Help: Organize cmake-developer.7 manual Modules section
Add "Module Documentation" and "Find Modules" subsections.  Add to
Modules/readme.txt a textual reference to the cmake-developer.7 manual
and, while at it, fix the wiki URL domain.
2013-10-22 10:10:15 -04:00
Kitware Robot 28f08ba25c Help: Fix module documentation markup in cmake-developer.7 manual
Convert the content moved from Modules/readme.txt to valid
reStructuredText markup.  Mainly, convert the lists of variables to
definition lists, wrap long lines in paragraph text, and add literal
block markup and indentation.
2013-10-22 10:09:26 -04:00
Kitware Robot baaab068f2 Help: Move Modules/readme.txt content into cmake-developer.7 manual
Move all content from Modules/readme.txt except for the link to the
module maintainers wiki page into "Help/manual/cmake-developer.7.rst".
This produces some invalid reStructuredText markup to be fixed in a
future commit.
2013-10-22 09:51:51 -04:00
Brad King 80a311ed6a Help: Add cmake-developer.7 manual
Add the manual with just an introduction section.  Leave section headers
for Help and Modules to be filled in later.
2013-10-22 09:50:15 -04:00