summaryrefslogtreecommitdiffstats
path: root/Utilities/Sphinx/cmake.py
Commit message (Collapse)AuthorAgeFilesLines
* Utilities/Sphinx: Restore html search index link anchorsBrad King2023-07-131-1/+1
| | | | | | | | | | | | | Since commit 37e015d4a6 (Utilities/Sphinx: Refactor Sphinx reference recording, 2023-03-08, v3.27.0-rc1~342^2~1), anchors in links to cmake domain objects generated in html search results were missing their object type prefix, and thus did not link to the object. Restore our `get_objects` implementation's second tuple entry to what we used prior to that commit. This matches what Sphinx's builtin python, rst, and javascript modes do. Fixes: #25067
* Merge topic 'sphinx-docutils-warning' into release-3.27Brad King2023-06-231-1/+12
|\ | | | | | | | | | | | | 0c14b6085a Utilities/Sphinx: Fix warning from docutils 0.18.1+ Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !8578
| * Utilities/Sphinx: Fix warning from docutils 0.18.1+Henry Schreiner2023-06-221-1/+12
| | | | | | | | | | Also might fix 0.18.0 exactly, which apparently forgot to add the backward compat shim.
* | Utilities/Sphinx: Fix parallel documentation buildsMatthew Woehlke2023-06-221-1/+15
|/ | | | | | | | | | | | | | | | In commit d78bfa1ecc (Utilities/Sphinx: support cmakedomain running in parallel, 2022-10-24, v3.26.0-rc1~495^2) we declared the domain as parallel-safe without actually implementing the required `merge_domaindata` method. Since then, commit 37e015d4a6 (Utilities/Sphinx: Refactor Sphinx reference recording) changed how we store resolved references, such that our separate fix for 3.26 does not work in 3.27+. While at it, correct a crusty comment that was overlooked during the aforementioned refactoring. Issue: #24076 Co-authored-by: Jared Dillard <jared.dillard@gmail.com>
* Utilities/Sphinx: Fix some flake8 gripesMatthew Woehlke2023-06-131-7/+6
| | | | Reorder some imports to better conform to what flake8 wants.
* Utilities/Sphinx: Don't ignore flake8 E402Matthew Woehlke2023-06-131-18/+18
| | | | | | | | Refactor commit 1f39a3cd1a (Utilities/Sphinx: Restore explicit check for Sphinx 2.x or later) to avoid needing to suppress flake8 E402. While ignoring it with respect to the docutils/sphinx imports and the sphinx version check was correct, the need to disable it for the whole file was suboptimal.
* Utilities/Sphinx: Restore explicit check for Sphinx 2.x or laterBrad King2023-06-121-3/+5
| | | | | | | | Refactoring in commit adbc8c982d (Utilities/Sphinx: Fix flake8 gripes in cmake.py, 2023-03-13, v3.27.0-rc1~317^2) moved the assertion added by commit cef51925a4 (Utilities/Sphinx: Require Sphinx 2.x or later, 2023-03-13, v3.27.0-rc1~317^2~2) to after imports, which is too late to clearly reject older Sphinx versions.
* Utilities/Sphinx: Fix flake8 E124 diagnostic in cmake.pyBrad King2023-06-121-1/+1
|
* Sphinx: Specify encoding when opening files for title extractionCraig Scott2023-04-071-2/+3
| | | | | | | | | | When the encoding is not specified, open() may choose an encoding based on the locale in use. That encoding may have no relationship to the encoding of the file being opened. Use the locale from the document settings instead, which should better match the file's encoding. Fixes: #24679
* Utilities/Sphinx: Fix flake8 gripes in cmake.pyMatthew Woehlke2023-03-151-42/+87
| | | | | | | | Edit Utilities/Sphinx/cmake.py to avoid lines longer than 79 characters and to obey other flake8-checked style rules. This will allow using flake8 to check for possible issues without having to wade through noise about improper styling. (Also, of course, consistent styling is beneficial in its own right.)
* Utilities/Sphinx: Use f-strings in cmake.pyMatthew Woehlke2023-03-151-16/+15
| | | | | | | | | Port all uses of old-style % string formatting to use f-strings. These are generally more readable (and tend to be shorter as well). Although this requires Python 3.6 or later, that should be available 'stock' on most or all platforms still under support, and besides, we were already using f-strings in some places.
* Utilities/Sphinx: Require Sphinx 2.x or laterMatthew Woehlke2023-03-151-36/+6
| | | | | | | Tweak our Sphinx extensions slightly to assert that Sphinx is at least 2.x. Remove hacks for older versions of Sphinx. This cleans up a bunch of messy code and, more importantly, paves the way for consolidating our import statements.
* Utilities/Sphinx: Add 'cref' roleMatthew Woehlke2023-03-141-1/+18
| | | | | | | | | | | | | Add a role that can be used to create local links (a la '`LINK`_'), but that also applies literal style. This is particularly useful for referring to subcommands within the command's documentation in a style that is consistent with ':command:`BAR <foo(BAR)>`' but is much less verbose. Although this is intended for subcommands, it works with any local reference. Co-authored-by: Brad King <brad.king@kitware.com>
* Utilities/Sphinx: Factor out part of CMakeXRefRoleMatthew Woehlke2023-03-141-13/+29
| | | | | | | Refactor the portion of CMakeXRefRole that escapes angle brackets in reference titles to the equivalent of a C++ template class. This will allow us to reuse that logic for reference roles that aren't derived from XRefRole.
* Utilities/Sphinx: Restore trailing parens on command cross-referencesBrad King2023-03-141-3/+8
| | | | | | | | | | Since commit cc21d0e478 (Utilities/Sphinx: Make signatures linkable, 2023-03-09) we always convert `cmake:command` domain cross-references to use the explicit `text <text>` form. This breaks the XRefRole's `fix_parens` setting that we use to render `cmd` as `cmd()`. Instead, transform `cmd(sub)` to `cmd(sub) <cmd(sub)>` to preserve the sub-command link destination, but leave `cmd` alone and let XRefRole convert it to `cmd()`.
* Merge topic 'smart-wrap-signatures'Brad King2023-03-141-12/+71
|\ | | | | | | | | | | | | 39ecaa5da1 Utilities/Sphinx: Improve word wrap of signatures Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !8317
| * Utilities/Sphinx: Improve word wrap of signaturesMatthew Woehlke2023-03-131-12/+71
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Implement logic to support several styles of parsing in the new signature directive that control where line breaks are allowed in a signature. The default is 'smart', which forbids breaks inside of square- or angle-brackets. The 'verbatim' option forbids all breaks. In all cases, breaks are always allowed where a newline appears in the source. This seems to Just Work for most writers, but HTML needs some special handling that is accomplished by a new CSS rule and assigning the 'nbsp' class to spaces that are not allowed to break. (ROFF's line wrapping is rather unfortunate here, as it prefers splitting and hyphenating words rather than breaking at a space.)
* | Utilities/Sphinx: Allow explicit target for genexMatthew Woehlke2023-03-131-5/+29
|/ | | | | | | | | | | | | | | | Split the genex directive into its own class, allowing a slight simplification of CMakeObject. Add ability to specify an explicit target name for the same. Use this to provide a target for the `$<TARGET_PROPERTY:prop>` generator expression which is otherwise missing one (due to overlap with `$<TARGET_PROPERTY:tgt,prop>`). With this one can write: :genex:`$<TARGET_PROPERTY:prop> <TARGET_PROPERTY:prop>` to link the second variant. Fixes: #24573
* Utilities/Sphinx: Make signatures linkableMatthew Woehlke2023-03-091-10/+29
| | | | | | | | | | | Add signatures to the collection of observed objects (which can be referenced elsewhere). Don't automatically strip parameters from a :command: reference, as these may now link signatures. (Do, however, munge them into 'text <ref>' form if they aren't already, as not doing so adds an extra '()' for some reason.) Correspondingly, change xref resolution to try to match 'command' when a ref like 'command(args)' is not matched, so that existing links to commands that have not been converted to use the new signature directive don't immediately break.
* Utilities/Sphinx: Refactor Sphinx reference recordingMatthew Woehlke2023-03-081-18/+39
| | | | | | | | | Rewrite how we record objects in our Sphinx extensions to more closely conform to how other domains do likewise, and to store more information than was previously being stored. This is a first step toward being able to record and reference signatures.
* Utilities/Sphinx: Add a directive to document command signaturesMatthew Woehlke2023-03-031-3/+82
| | | | | | | Add a `signature` directive to offer a CMake version of Sphinx's `function` directive, similar to that found in other domains (py, cpp, etc.). Like others, this takes one or more signatures as arguments and creates dt/dd nodes from the signatures and the directive contents.
* Utilities/Sphinx: Drop commented-out code from cmake domain implBrad King2023-02-241-12/+1
| | | | Inspired-by: Alex Turbov <i.zaufi@gmail.com>
* Utilities/Sphinx: support cmakedomain running in parallelHenry Schreiner2022-10-241-0/+1
| | | | | | Fixes: #24076 Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
* Utilities/Sphinx: Avoid deprecated docutils error handling helpersBrad King2022-10-111-12/+6
| | | | | | | | | | The `SafeString` and `ErrorString` classes are deprecated and will be removed in Docutils 0.21 or later. They help avoid encoding errors during exception handling in Python <= 2.7, but these days we always use Python 3 to build the documentation, at least during development, when error cases are most likely to occur. Fixes: #24039
* Utilities/Sphinx: Index guide section documents for cross-referencingBrad King2021-06-171-0/+11
| | | | | | | | Extend the change from commit 6185265800 (Utilities/Sphinx: Index guide-level documents for cross-referencing, 2019-12-06, v3.17.0-rc1~181^2~1) to name guide documents other than the top level using their docname instead of their title. This will allow them to be cross-referenced by a stable name even if their title changes.
* Utilities: Fix typos and spelling in commentsJosef Angstenberger2021-05-071-1/+1
|
* Utilities/Sphinx: Add role and directive for 'genex' in CMake domainBrad King2021-01-181-2/+19
| | | | | | | | | | | | | | | | | This enables cross-reference syntax for CMake generator expressions: :genex:`SOME_GENEX` :genex:`$<SOME_GENEX>` :genex:`$<SOME_GENEX:...>` and definition of CMake generator expressions via a directive: .. genex:: SOME_GENEX .. genex:: $<SOME_GENEX> .. genex:: $<SOME_GENEX:...> It also adds generator expressions defined by the directive and by `Help/genex/SOME_GENEX.rst` documents to the index.
* Utilities/Sphinx: Avoid using deprecated sphinx APIsBrad King2020-10-051-19/+23
| | | | | | | | Sphinx has deprecated `sphinx.util.pycompat.htmlescape` and `sphinx.builders.qthelp.QtHelpBuilder`. We only import these as part of a monkey-patch to work around a bug in versions of sphinx before 1.7.2, so make that code path conditional. The imports are not deprecated on the versions where we need them.
* Utilities/Sphinx: Clarify check for sphinx < 1.4Brad King2020-10-051-8/+4
|
* Utilities/Sphinx: Index guide-level documents for cross-referencingBrad King2020-01-131-0/+3
| | | | | | Extend the change from commit d2fde94809 (Help: Add infrastructure for guide-level documentation, 2019-05-30, v3.16.0-rc1~531^2~4) to add support for cross-referencing and indexing the guides.
* Utilities/Sphinx: Index document types only by top level directoryBrad King2020-01-131-1/+1
| | | | | | | We use the convention `Help/<type>/<doc>` for indexing each document as an object of type `<type>`. Split the document name on the first slash rather than the last slash so that multi-level documents like `Help/guide/tutorial/index.rst` are indexed as their top-level type.
* Sphinx: Add limited support for nested variables in docsCraig Scott2019-01-261-1/+4
| | | | This is needed to allow example code to contain content like `${some_${foo}_bar}`.
* Help: Override pygments CMakeLexer to support <..> and [..]Joachim Wuttke (o)2018-10-181-6/+47
| | | | | | | | | | | | | | | | | | | | | | * The code snippets in the docs consist of CMake code mixed with syntax definition punctuation like < > [ ] ... Therefore a pure CMake lexer is inadequate. Here it is replaced by a CMake syntax definition parser. * Fixed syntax definition snippets in FindPkgConfig.cmake to make best use of syntax highlighting. This source file is the hardest to support because it contains comparison operators <= = >=, which need special attention to avoid confusion with the placeholder indicators <...>. * Fixed syntax in execute_process.rst (there were unbalanced brackets). * Disabled syntax highlighting for long string examples in cmake-language.7.rst. * No highlighting of removed syntax in CMP0049 * To inspect the outcome of this patch, see e.g. the pages * manual/cmake-buildsystem.7.html * module/ExternalProject.html * module/FindPkgConfig.html which are particularly rich in complex code snippets.
* Help: Add new section for CPack generatorsKyle Edwards2018-06-211-0/+3
| | | | | | | | | | | | | | | | | | | | The documentation for CPack generators previously lived in their respective internal CMake modules. This setup was misleading, because it implied that you should include the modules in your own code, which is not the case. Moving the documentation into a separate section does a better job of hiding the internal modules, which are just an implementation detail. The generator documentation has also been modified to remove any references to the module name. The CPackIFW module is a special exception: since it has user-facing macros, the documentation for these macros has been kept in the module page, while all other documentation related to the IFW generator has been moved into the new section. To make it easier to find the new documentation, the old help pages for the CPack*.cmake modules have not been deleted, but have been replaced with a link to their respective help page in the new documentation section.
* Fix misc. typosluz.paz2018-06-041-1/+1
| | | | Found via `codespell` and `grep`
* Utilities/Sphinx: Add role and directive for 'envvar' in CMake domainBrad King2018-04-191-0/+4
| | | | | | | | | | | | | | | | | | | | | | This enables cross-reference syntax for CMake environment variables: :envvar:`SOMEVAR` and definition of CMake environment variables via a directive: .. envvar:: SOMEVAR It also adds environment variables defined by the directive and by `Help/envvar/SOMEVAR.rst` documents to the index. This `envvar` role and directive is defined in our `cmake` domain and overrides the equivalent `envvar` role and directive provided by Sphinx in its default domain. This is okay because we build CMake documents in the `cmakd` domain. This follows up the work from commit v3.10.0-rc1~43^2 (Help: Document CMake's environment variables, 2017-09-01) that originally added `envvar` documentation.
* Utilities/Sphinx: Restore compatibility with Sphinx pre-1.2Björn Esser2017-08-021-2/+15
| | | | | | | | Since commit v3.8.0-rc2~28^2~2 (Utilities/Sphinx: Port cmake extension to Sphinx 1.4, 2017-02-09) we use the `sphinx.version_info` tuple. However, it was added in Sphinx v1.2 so the check breaks compatibility with older versions. Revise our check to assume Sphinx pre-1.2 if the version tuple does not exist.
* Utilities/Sphinx: Port cmake extension to Sphinx 1.4Gregor Jasny2017-02-101-2/+6
| | | | | | | | Sphinx 1.4 introduced a breaking change to `indexnode` by changing the length of a tuple. Teach our extension to produce a tuple of the proper length for the version of Sphinx in use. This gets rid of the "4 column based index found" warning.
* Simplify CMake per-source license noticesBrad King2016-09-271-11/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | Per-source copyright/license notice headers that spell out copyright holder names and years are hard to maintain and often out-of-date or plain wrong. Precise contributor information is already maintained automatically by the version control tool. Ultimately it is the receiver of a file who is responsible for determining its licensing status, and per-source notices are merely a convenience. Therefore it is simpler and more accurate for each source to have a generic notice of the license name and references to more detailed information on copyright holders and full license terms. Our `Copyright.txt` file now contains a list of Contributors whose names appeared source-level copyright notices. It also references version control history for more precise information. Therefore we no longer need to spell out the list of Contributors in each source file notice. Replace CMake per-source copyright/license notice headers with a short description of the license and links to `Copyright.txt` and online information available from "https://cmake.org/licensing". The online URL also handles cases of modules being copied out of our source into other projects, so we can drop our notices about replacing links with full license text. Run the `Utilities/Scripts/filter-notices.bash` script to perform the majority of the replacements mechanically. Manually fix up shebang lines and trailing newlines in a few files. Manually update the notices in a few files that the script does not handle.
* Utilities/Sphinx: Fix link targets for mixed-case command namesBrad King2014-12-041-2/+10
| | | | | | | | When a CMake domain 'command' object is defined by CMakeTransform or the 'cmake:command' directive, generate the link target with a lower-case name even if the command name is not all lower-case. This is needed to make cross-references to the command definition work since the 'cmake:command' role is marked with the 'lowercase' property.
* Utilities/Sphinx: Add missing call to note_explicit_targetBrad King2014-11-171-0/+1
| | | | | | Sphinx calls document.note_explicit_target with any nodes.target() it creates. Add such a call when we create a document target in CMakeTransform.
* Utilities/Sphinx: Add index entries for cross-referencesBrad King2014-11-121-2/+46
| | | | | | | Add a document transform to insert index and target nodes just before any CMake domain cross-reference node. This will make references to CMake domain objects appear in the index. Also add a comment explaining why it cannot be done in a result_nodes method of the CMakeXRefRole.
* Add an "installed file" property scopeNils Gladitz2014-05-281-0/+4
| | | | | | | 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.
* Merge topic 'sphinx-python3'Brad King2014-04-241-1/+4
|\ | | | | | | | | d55671ad Utilities/Sphinx: Fix cmake domain document removal with python3
| * Utilities/Sphinx: Fix cmake domain document removal with python3Brad King2014-04-241-1/+4
| | | | | | | | | | | | In the domain clear_doc method, avoid removing entries from a dictionary while iterating over it. Instead accumulate a set of entries to remove at the end.
* | Merge topic 'sphinx-python3'Brad King2014-04-181-3/+3
|\ \ | |/ | | | | | | 69069cfb Utilities/Sphinx: Port documentation generation to python3 (#14886)
| * Utilities/Sphinx: Port documentation generation to python3 (#14886)Uwe L. Korn2014-04-181-3/+3
| |
* | Help: Add option to create and install Qt .qch file.Stephen Kelly2014-03-311-0/+18
|/
* Help: Workaround pygments reporting an error for genexes.Stephen Kelly2014-01-041-0/+10
| | | | | Without the workaround, CMake code snippets are not highlighted at all because pygments can not lex the generator expressions.
* Help: Fix Sphinx extension with docutils < 0.11Alex Neundorf2013-12-231-1/+6
| | | | | | | In older versions of python docutils "error_reporting" was not in the "utils" subpackage, so try the older location if the new one failed. Alex
generated by cgit v0.12 at 2024-12-28 17:16:15 (GMT)