Improve examples and work on RTD landing page

Author: William McLendon

README.md

@@ -292,8 +292,13 @@ be provided in the `opt-set-cmake-var` operation in the .ini file:
 SetProgramOptionsCMake Examples
 -------------------------------
 
-### [example-02.ini](examples/example-02.ini)
+### Example 02
+
+**example-02.ini**
 ```ini
+#
+# example-02.ini
+#
 [CMAKE_COMMAND]
 opt-set cmake
 
@@ -304,9 +309,9 @@ opt-set -G : Ninja
 opt-set -G : "Unix Makefiles"
 
 [MYPROJ_OPTIONS]
-opt-set-cmake-var  MYPROJ_CXX_FLAGS                         : "-O0 -fopenmp"
-opt-set-cmake-var  MYPROJ_ENABLE_OPTION_A BOOL FORCE        : ON
-opt-set-cmake-var  MYPROJ_ENABLE_OPTION_B BOOL PARENT_SCOPE : ON
+opt-set-cmake-var  MYPROJ_CXX_FLAGS       STRING       : "-O0 -fopenmp"
+opt-set-cmake-var  MYPROJ_ENABLE_OPTION_A BOOL   FORCE : ON
+opt-set-cmake-var  MYPROJ_ENABLE_OPTION_B BOOL         : ON
 
 [MYPROJ_SOURCE_DIR]
 opt-set /path/to/source/dir
@@ -324,18 +329,22 @@ use MYPROJ_OPTIONS
 use MYPROJ_SOURCE_DIR
 ```
 
-### [example-02.py](examples/example-02.py)
+**example-02.py**
 ```python
 #!/usr/bin/env python3
-import os
-import sys
-
+# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
+from pathlib import Path
 import setprogramoptions
 
+print(80*"-")
+print(f"- {Path(__file__).name}")
+print(80*"-")
+
+
 filename = "example-02.ini"
 popts = setprogramoptions.SetProgramOptionsCMake(filename)
 
-section  = "MYPROJ_CONFIGURATION_NINJA"
+section = "MYPROJ_CONFIGURATION_NINJA"
 popts.parse_section(section)
 
 # Generate BASH output
@@ -357,26 +366,27 @@ print("\nDone")
 Generates the output:
 ```bash
 $ python3 example-02.py
+--------------------------------------------------------------------------------
+- example-02.py
+--------------------------------------------------------------------------------
 
-Bash output
------------
+**Bash output**
 cmake \
    -G=Ninja \
-   -DMYPROJ_CXX_FLAGS="-O0 -fopenmp" \
+   -DMYPROJ_CXX_FLAGS:STRING="-O0 -fopenmp" \
    -DMYPROJ_ENABLE_OPTION_A:BOOL=ON \
    -DMYPROJ_ENABLE_OPTION_B:BOOL=ON \
    /path/to/source/dir
 
 CMake fragment output
 ---------------------
-set(MYPROJ_CXX_FLAGS "-O0 -fopenmp")
+set(MYPROJ_CXX_FLAGS "-O0 -fopenmp" CACHE STRING "from .ini configuration")
 set(MYPROJ_ENABLE_OPTION_A ON CACHE BOOL "from .ini configuration" FORCE)
-set(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL "from .ini configuration" PARENT_SCOPE)
+set(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL "from .ini configuration")
 
 Done
 ```
 
-
 [1]: https://cmake.org/cmake/help/latest/command/set.html
 [2]: https://github.com/sandialabs/ConfigParserEnhanced
 [3]: https://github.com/sandialabs/SetProgramOptions/blob/master/CHANGELOG.md

doc/source/index.rst

@@ -3,24 +3,177 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to SetProgramOptions documentation!
-===========================================
+SetProgramOptions Python Module
+===============================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: Table of Contents:
 
    SetProgramOptions
    SetProgramOptionsCMake
    License <License>
 
 
 
-Indices and tables
-==================
+Indices and Tables
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 
 
+Overview
+========
+TODO: This needs to be expanded for RTD.
+
+
+Examples
+========
+Here we show a few examples of how ``SetProgramOptions`` and
+``SetProgramOptionsCMake`` can be used.
+
+Example 1
+---------
+In example-01 we have a fairly simple .ini file that demostrates utilization
+of the ``use`` operation that comes built in with
+`ConfigParserEnhanced <https://pypi.org/project/configparserenhanced/>`_.
+In this example we are going to demonstrate how the ``opt-set`` operations
+in our .ini file can be used to generate a custom bash command with
+customizable argument sets added.
+
+In this case, we will process the ``[MY_LS_COMMAND]`` section to generate
+a bash command that would generate a directory listing in list form by
+reverse time order of last modified with a custom timestamp format.
+
+While this example is quite simple we can see how a complex environment
+in a DevOps setting might use this to bundle "common" operations to reduce
+the amount of copying and pasting that is used.
+
+example-01.ini
+++++++++++++++
+.. literalinclude:: ../../examples/example-01.ini
+    :language: ini
+    :linenos:
+
+example-01.py
++++++++++++++
+.. literalinclude:: ../../examples/example-01.py
+    :language: python
+    :linenos:
+
+Console Output
+++++++++++++++
+.. literalinclude:: ../../examples/example-01.log
+    :language: text
+    :linenos:
+
+Example 2
+---------
+Example 2 demonstrates the use of ``SetProgramOptionsCMake``
+which is a *subclass* of ``SetProgramOptions`` and implements
+*operations* for handling *CMake* variables in a .ini file.
+SetProgramOptionsCMake also introduces a new "CMake fragment"
+generator and implements logic to maintain consistency of
+behavior between generated BASH scripts and CMake fragments
+with knoweldge of how CMake treats ``-D`` operations at the
+command line versus ``set()`` operations inside a CMake script.
+
+Here we show the new operation ``opt-set-cmake-var`` which
+has the form ``opt-set-cmake-var VARNAME <OPTIONAL PARAMS> : VALUE``.
+Details and a comprehensive list of the optional parameters can
+be found in the ``SetProgramOptionsCMake`` Class Reference page.
+
+The main elements this example will demonstrate is how to use
+``opt-set-cmake-var`` operations and how they can be used.
+
+This example is fairly straightforward since the .ini file
+options being defined will generate the same output for both
+generator types.
+
+example-02.ini
+++++++++++++++
+.. literalinclude:: ../../examples/example-02.ini
+    :language: ini
+    :linenos:
+
+example-02.py
++++++++++++++
+.. literalinclude:: ../../examples/example-02.py
+    :language: python
+    :linenos:
+
+Console Output
+++++++++++++++
+.. literalinclude:: ../../examples/example-02.log
+    :language: text
+    :linenos:
+
+
+
+Example 3
+---------
+The last example we show here is a bit more complicated and gets into
+some of the differences in how CMake treats a *command line* variable
+being set via a ``-D`` option versus a ``set()`` operation within a
+CMakeLists.txt file.
+
+The script prints out a notice explaining the nuance but the general
+idea is that CMake treats options provided by a ``-D`` option at the
+command line as though they are ``CACHE`` variables with the ``FORCE``
+option enabled. This is designed to allow command-line parameters to
+generally take precedence over what a CMakeLists.txt file might set
+as though it's a user-override. The added ``FORCE`` option also ensures
+that if there are multiple ``-D`` options setting the same variable the
+*last* one will win.
+
+This can have a subtle yet profound effect on how we must process our
+``opt-set-cmake-var`` operations within a .ini file if our goal is to
+ensure that the resulting ``CMakeCache.txt`` file generated by a CMake
+run would be the same for both *bash* and *cmake fragment* generators.
+
+In this case, in order to have a variable be set by the *bash* generator
+it must be a ``CACHE`` variable -- which can be accomplished by either
+adding a *TYPE* or a *FORCE* option.
+We will note here that if ``FORCE`` is given without a *TYPE* then we
+use the default type of *STRING*.
+
+If the *same* CMake variable is being assigned, such as in a case where
+we have a section that is updating a flag, then the `FORCE` option must
+be present on the second and all subsequent occurrences of ``opt-set-cmake-var``
+or the *bash* generator will skip over that assignment since a non-forced
+``set()`` operation in CMake would not overwrite an existing cache var.
+This situation can occur frequently if our .ini file(s) are structured to
+have some *common* configuration option set and then a specialization which
+updates one of the arguments. One example of this kind of situation might
+be where we have a specialization that adds OpenMP and we would want to add
+the ``-fopenmp`` flags to our linker flags.
+
+example-03.ini
+++++++++++++++
+.. literalinclude:: ../../examples/example-03.ini
+    :language: ini
+    :linenos:
+
+example-03.py
++++++++++++++
+.. literalinclude:: ../../examples/example-03.py
+    :language: python
+    :linenos:
+
+Console Output
+++++++++++++++
+.. literalinclude:: ../../examples/example-03.log
+    :language: text
+    :linenos:
+
+We will note here that the *CMake* fragment generator will still generate
+all of the commands. In this case the second ``set()`` command would be ignored
+by CMake since it's not FORCEd but the main take-away here is that the
+*bash* generator omitted the second ``-D`` operation since that would be
+a ``FORCE`` operation by default which is not representative of what was
+specified in the .ini file.
+
+
+

examples/example-01.ini

@@ -1,12 +1,6 @@
-#==============================================================================
-# SetProgramOptions Example
-#==============================================================================
-
-
-[BASH_VERSION]
-opt-set bash
-opt-set --version
-
+#
+# example-01.ini
+#
 [LS_COMMAND]
 opt-set ls
 

examples/example-02.ini

@@ -7,9 +7,6 @@ opt-set cmake
 [CMAKE_GENERATOR_NINJA]
 opt-set -G : Ninja
 
-[CMAKE_GENERATOR_MAKEFILES]
-opt-set -G : "Unix Makefiles"
-
 [MYPROJ_OPTIONS]
 opt-set-cmake-var  MYPROJ_CXX_FLAGS       STRING       : "-O0 -fopenmp"
 opt-set-cmake-var  MYPROJ_ENABLE_OPTION_A BOOL   FORCE : ON
@@ -23,9 +20,3 @@ use CMAKE_COMMAND
 use CMAKE_GENERATOR_NINJA
 use MYPROJ_OPTIONS
 use MYPROJ_SOURCE_DIR
-
-[MYPROJ_CONFIGURATION_MAKEFILES]
-use CMAKE_COMMAND
-use CMAKE_GENERATOR_MAKEFILES
-use MYPROJ_OPTIONS
-use MYPROJ_SOURCE_DIR

examples/example-02.log

@@ -2,17 +2,17 @@
 - example-02.py
 --------------------------------------------------------------------------------
 
-Bash output
------------
+Generate Bash Output
+--------------------
 cmake \
    -G=Ninja \
    -DMYPROJ_CXX_FLAGS:STRING="-O0 -fopenmp" \
    -DMYPROJ_ENABLE_OPTION_A:BOOL=ON \
    -DMYPROJ_ENABLE_OPTION_B:BOOL=ON \
    /path/to/source/dir
 
-CMake fragment output
----------------------
+Generate CMake Fragment
+-----------------------
 set(MYPROJ_CXX_FLAGS "-O0 -fopenmp" CACHE STRING "from .ini configuration")
 set(MYPROJ_ENABLE_OPTION_A ON CACHE BOOL "from .ini configuration" FORCE)
 set(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL "from .ini configuration")

examples/example-02.py

@@ -3,28 +3,29 @@
 from pathlib import Path
 import setprogramoptions
 
+def print_separator(label):
+    print("")
+    print(f"{label}")
+    print("-"*len(label))
+    return
+
 print(80*"-")
 print(f"- {Path(__file__).name}")
 print(80*"-")
 
-
 filename = "example-02.ini"
 popts = setprogramoptions.SetProgramOptionsCMake(filename)
 
 section = "MYPROJ_CONFIGURATION_NINJA"
 popts.parse_section(section)
 
 # Generate BASH output
-print("")
-print("Bash output")
-print("-----------")
+print_separator("Generate Bash Output")
 bash_options = popts.gen_option_list(section, generator="bash")
 print(" \\\n   ".join(bash_options))
 
 # Generate a CMake Fragment
-print("")
-print("CMake fragment output")
-print("---------------------")
+print_separator("Generate CMake Fragment")
 cmake_options = popts.gen_option_list(section, generator="cmake_fragment")
 print("\n".join(cmake_options))
 

examples/example-03.ini

@@ -1,9 +1,6 @@
-# ------------------------------------------------------------------------------
 #
-# Example with variable expansion with SetProgramOptionsCMake
+# example-03.ini
 #
-# ------------------------------------------------------------------------------
-
 [TEST_VAR_EXPANSION_COMMON]
 opt-set-cmake-var CMAKE_CXX_FLAGS STRING : "${LDFLAGS|ENV} -foo"