From f3d5d3956c231b1325541e248058f692fb03cd93 Mon Sep 17 00:00:00 2001 From: Michael Fabian 'Xaymar' Dirks Date: Mon, 4 Jul 2022 05:34:16 +0200 Subject: [PATCH] docs: Reduce generated bloat This is a single function, no need for more than the index --- docs/conf.py | 2 +- docs/index.rst | 79 +++++++++++++++++++++++++++++++++++++++++++++--- docs/version.rst | 76 ---------------------------------------------- 3 files changed, 75 insertions(+), 82 deletions(-) delete mode 100644 docs/version.rst diff --git a/docs/conf.py b/docs/conf.py index 08b9b95..de48a00 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,4 +53,4 @@ html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = [] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 69167dc..23fc3d5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,76 @@ -Version handling for CMake -========================================= +version +------- -.. toctree:: - :maxdepth: 1 +Generate, parse and modify versions purely with CMake. Supports Semantic Versioning 2.0.0, 1.0.0 and other version formats. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + version(`PARSE`_ ) + version(`GENERATE`_ [COMPRESS] [MAJOR ] [MINOR ] [PATCH ] [TWEAK ] [PRERELEASE ] [BUILD ]) + version(`MODIFY`_ [COMPRESS] [MAJOR ] [MINOR ] [TWEAK ] [PRERELEASE ] [BUILD ]) + version(`COMPARE`_ ) + + +The following version constructs are currently supported: + +.. code-block:: + + "." ["." ["." ]] + "." ["." ["." ]] [["-"] ] ["+" ] + + +Parsing +^^^^^^^ + +.. _PARSE: + +.. code-block:: cmake + + version(PARSE ) + +Attempts to parse the version in ```` and stores the individual compoents into ``_``. If a component is not present in the given version, it will be undefined. If an error occurred, ``_ERROR`` will be defined and contain the error message. + +Generating +^^^^^^^^^^ + +.. _GENERATE: + +.. code-block:: cmake + + version(GENERATE [COMPRESS] [MAJOR ] [MINOR ] [PATCH ] [TWEAK ] [PRERELEASE ] [BUILD ]) + +Generates a version from the components provided and stores the result in ````. The components ```` and ```` will default to ``0`` if not provided. If an error occurred, ``_ERROR`` will be defined and contain the error message. + +Modifying +^^^^^^^^^ + +.. _MODIFY: + +.. code-block:: cmake + + version(MODIFY [COMPRESS] [MAJOR ] [MINOR ] [TWEAK ] [PRERELEASE ] [BUILD ]) + +Modifies the version provided in ```` with the components provided. The components ````, ````, ```` and ```` may have a prefix of ``+`` or ``-`` to add and subtract the value, or no prefix to replace. The result of this operation will be stored as a string in ````. If a component did not exist in the original, it will be added to the version as a replace operation. If an error occurred, ``_ERROR`` will be defined and contain the error message. + +Comparing +^^^^^^^^^ + +.. _COMPARE: + +.. code-block:: cmake + + version(COMPARE ) + +Compares the version ```` against ```` and stores the result in ````. The provided version will be evaluated in the order MAJOR, MINOR, PATCH, TWEAK, PRERELEASE, and then BUILD. The following results should be expected: + +- If a component is only in ````, ```` will contain the componenent name prefixed by ``+``. +- If a component is only in ````, ```` will contain the componenent name prefixed by ``-``. +- If a component is numerical and the value is larger in ````, ```` will contain the componenent name prefixed by ``>``. +- If a component is numerical and the value is larger in ````, ```` will contain the componenent name prefixed by ``<``. +- If a component is alphanumerical and the value is different in either, ```` will contain the component name with no prefix. +- In all other cases, ```` will be empty. +- If an error occurred, ``_ERROR`` will be defined and contain the error message, and ```` will be undefined. - version diff --git a/docs/version.rst b/docs/version.rst deleted file mode 100644 index 23fc3d5..0000000 --- a/docs/version.rst +++ /dev/null @@ -1,76 +0,0 @@ -version -------- - -Generate, parse and modify versions purely with CMake. Supports Semantic Versioning 2.0.0, 1.0.0 and other version formats. - -Synopsis -^^^^^^^^ - -.. parsed-literal:: - - version(`PARSE`_ ) - version(`GENERATE`_ [COMPRESS] [MAJOR ] [MINOR ] [PATCH ] [TWEAK ] [PRERELEASE ] [BUILD ]) - version(`MODIFY`_ [COMPRESS] [MAJOR ] [MINOR ] [TWEAK ] [PRERELEASE ] [BUILD ]) - version(`COMPARE`_ ) - - -The following version constructs are currently supported: - -.. code-block:: - - "." ["." ["." ]] - "." ["." ["." ]] [["-"] ] ["+" ] - - -Parsing -^^^^^^^ - -.. _PARSE: - -.. code-block:: cmake - - version(PARSE ) - -Attempts to parse the version in ```` and stores the individual compoents into ``_``. If a component is not present in the given version, it will be undefined. If an error occurred, ``_ERROR`` will be defined and contain the error message. - -Generating -^^^^^^^^^^ - -.. _GENERATE: - -.. code-block:: cmake - - version(GENERATE [COMPRESS] [MAJOR ] [MINOR ] [PATCH ] [TWEAK ] [PRERELEASE ] [BUILD ]) - -Generates a version from the components provided and stores the result in ````. The components ```` and ```` will default to ``0`` if not provided. If an error occurred, ``_ERROR`` will be defined and contain the error message. - -Modifying -^^^^^^^^^ - -.. _MODIFY: - -.. code-block:: cmake - - version(MODIFY [COMPRESS] [MAJOR ] [MINOR ] [TWEAK ] [PRERELEASE ] [BUILD ]) - -Modifies the version provided in ```` with the components provided. The components ````, ````, ```` and ```` may have a prefix of ``+`` or ``-`` to add and subtract the value, or no prefix to replace. The result of this operation will be stored as a string in ````. If a component did not exist in the original, it will be added to the version as a replace operation. If an error occurred, ``_ERROR`` will be defined and contain the error message. - -Comparing -^^^^^^^^^ - -.. _COMPARE: - -.. code-block:: cmake - - version(COMPARE ) - -Compares the version ```` against ```` and stores the result in ````. The provided version will be evaluated in the order MAJOR, MINOR, PATCH, TWEAK, PRERELEASE, and then BUILD. The following results should be expected: - -- If a component is only in ````, ```` will contain the componenent name prefixed by ``+``. -- If a component is only in ````, ```` will contain the componenent name prefixed by ``-``. -- If a component is numerical and the value is larger in ````, ```` will contain the componenent name prefixed by ``>``. -- If a component is numerical and the value is larger in ````, ```` will contain the componenent name prefixed by ``<``. -- If a component is alphanumerical and the value is different in either, ```` will contain the component name with no prefix. -- In all other cases, ```` will be empty. -- If an error occurred, ``_ERROR`` will be defined and contain the error message, and ```` will be undefined. -