Updated docs

jrmadsen · Jan 16, 2019 · 85e10b0 · 85e10b0
1 parent 0e7ee47
commit 85e10b0
Show file tree

Hide file tree

Showing 4 changed files with 140 additions and 89 deletions.
diff --git a/docs/about.rst b/docs/about.rst
@@ -47,26 +47,23 @@ extension that uses ``nosetests`` for unit-testing:
 
     #!/usr/bin/env python
 
-    import os, sys, platform
+    import os
+    import sys
+    import platform
     import pyctest.pyctest as pyctest
     import pyctest.helpers as helpers
 
-    parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd())
-    parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
+    parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(),binary_dir=os.getcwd(), vcs_type="git")
     args = parser.parse_args()
 
     pyctest.BUILD_NAME = "{}".format(args.build)
     pyctest.BUILD_COMMAND = "python setup.py build_ext --inplace"
-    pyctest.UPDATE_COMMAND = "git"
 
     test = pyctest.test()
     test.SetName("unittest")
-    # insert the command to run the tests for project
     test.SetCommand(["nosetests"])
 
-    pyctest.generate_config()
-    pyctest.generate_test_file()
-    pyctest.run(pyctest.ARGUMENTS)
+    pyctest.run()
 
 Example for autotools project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -75,12 +72,15 @@ Example for autotools project
 
     #!/usr/bin/env python
 
-    import os, sys, platform
+    import os
+    import sys
+    import platform
     import multiprocessing as mp
     import pyctest.pyctest as pyctest
     import pyctest.helpers as helpers
 
-    parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd())
+    parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd(),
+                                    vcs_type="git")
     parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
     args = parser.parse_args()
 
@@ -91,18 +91,13 @@ Example for autotools project
     cmd.Execute()
 
     pyctest.BUILD_NAME = "{}".format(args.build)
-    pyctest.UPDATE_COMMAND = "git"
     pyctest.CONFIGURE_COMMAND = "./configure"
     pyctest.BUILD_COMMAND = "make -j{}".format(mp.cpu_count())
 
-    test = pyctest.test()
-    test.SetName("unittest")
-    # insert the command to run the tests for project
-    test.SetCommand(["./run-testing.sh"])
+    # alternate test declaration format
+    pyctest.test("unittest", ["./run-testing.sh"])
 
-    pyctest.generate_config()
-    pyctest.generate_test_file()
-    pyctest.run(pyctest.ARGUMENTS)
+    pyctest.run()
 
 Example for CMake project
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -118,24 +113,21 @@ Example for CMake project
     import pyctest.pyctest as pyctest
     import pyctest.helpers as helpers
 
-    binary_dir = os.path.join(os.getcwd(), "build-ProjectName")
+    project = "PyCTestDemo"
+    binary_dir = os.path.join(os.getcwd(), "{}-build".format(project))
     parser = helpers.ArgumentParser("ProjectName", os.getcwd(), binary_dir)
     parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
     args = parser.parse_args()
 
     pyctest.BUILD_NAME = "{}".format(args.build)
     pyctest.UPDATE_COMMAND = "git"
     pyctest.CONFIGURE_COMMAND = "cmake {}".format(pyctest.SOURCE_DIRECTORY)
-    pyctest.BUILD_COMMAND = "cmake --build {} --target all -- -j{}".format(pyctest.BINARY_DIRECTORY, mp.cpu_count())
+    pyctest.BUILD_COMMAND = "cmake --build {} --target all -- -j{}".format(
+        pyctest.BINARY_DIRECTORY, mp.cpu_count())
 
-    test = pyctest.test()
-    test.SetName("unittest")
-    # insert the command to run the tests for project
-    test.SetCommand(["./run-testing.sh"])
+    pyctest.test("unittest", ["./run-testing.sh"])
 
-    pyctest.generate_config(pyctest.BINARY_DIRECTORY)
-    pyctest.generate_test_file(pyctest.BINARY_DIRECTORY)
-    pyctest.run(pyctest.ARGUMENTS, pyctest.BINARY_DIRECTORY)
+    pyctest.run()
 
 Python Modules
 ~~~~~~~~~~~~~~
@@ -155,6 +147,34 @@ Python Modules
    -  It is possible to call CMake from this package but it is generally
       not the purpose
 
+Direct Access to CMake/CTest/CPack Executables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``python -m pyctest.cmake <ARGS>`` == ``cmake <ARGS>``
+- ``python -m pyctest.ctest <ARGS>`` == ``ctest <ARGS>``
+- ``python -m pyctest.cpack <ARGS>`` == ``cpack <ARGS>``
+
+Following Python code:
+
+.. code:: python
+
+    from pyctest.ctest import CTest
+    from pyctest.cmake import CMake
+    from pyctest.cpack import CPack
+
+    CMake({"CMAKE_BUILD_TYPE":"Release"}, os.getcwd(), "-G", "Ninja")
+    CTest("--build-and-test", os.getcwd(), "-VV")
+    CPack("-G", "TGZ")
+
+is equivalent to the following shell commands:
+
+.. code:: bash
+
+    cmake -DCMAKE_BUILD_TYPE=Release ${PWD} -G Ninja
+    ctest --build-and-test ${PWD} -VV
+    cpack -G TGZ
+
+
 Benefits
 ~~~~~~~~
 
@@ -237,10 +257,7 @@ without any configuration, build, etc. steps
 
     import os
     import sys
-    import shutil
-    import argparse
     import platform
-    import traceback
 
     import pyctest.pyctest as pyctest
     import pyctest.pycmake as pycmake
@@ -263,49 +280,50 @@ without any configuration, build, etc. steps
         pyctest.MODEL = "Continuous"
         pyctest.SITE = platform.node()
 
-        # create a Test object
+        # create a test
         test = pyctest.test()
         test.SetName("list_directory")
         test.SetCommand(["ls", directory])
         test.SetProperty("WORKING_DIRECTORY", os.getcwd())
 
         # create a second test
-        # previous test is already stored by PyCTest
-        test = pyctest.test()
-        test.SetName("hostname")
-        test.SetCommand(["hostname"])
-        test.SetProperty("TIMEOUT", "10")
-
-        # generate the CTestConfig.cmake and CTestCustom.cmake
-        pyctest.generate_config(directory)
-
-        # generate the CTestTestfile.cmake file
-        pyctest.generate_test_file(directory)
+        pyctest.test("hostname", ["hostname"], {"TIMEOUT": "10"})
 
         # run CTest -- e.g. ctest -VV ${PWD}/pycm-test
-        pyctest.run(pyctest.ARGUMENTS, directory)
+        pyctest.run()
 
 .. code:: bash
 
+    #############################################
+    #  ____  _  _  ___  ____  ____  ____  ____  #
+    # (  _ \( \/ )/ __)(_  _)(  __)/ ___)(_  _) #
+    #  ) __/ )  /( (__   )(   ) _) \___ \  )(   #
+    # (__)  (__/  \___) (__) (____)(____/ (__)  #
+    #                                           #
+    #############################################
+
+    PyCTest args: []
+    CTest args: []
+    CMake args: []
     CTest arguments (default): '-V -DSTAGES=Start;Update;Configure;Build;Test;Coverage;MemCheck -S Stages.cmake -j1'
-    Writing CTest test file: "/Users/jrmadsen/devel/c++/pyctest-master/pycm-test/CTestTestfile.cmake"...
+    Writing CTest test file: "/Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test/CTestTestfile.cmake"...
     Generating test "list_directory"...
     Generating test "hostname"...
     -- STAGES = Start;Update;Configure;Build;Test;Coverage;MemCheck
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Running CTEST_START stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Running CTEST_START stage...
     Run dashboard with model Continuous
-       Source directory: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
-       Build directory: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
-       Track: Continuous
-       Reading ctest configuration file: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test/CTestConfig.cmake
-       Site: JRM-macOS-DOE.local
-       Build name: [Darwin macOS 10.13.6 x86_64] [Python 3.6.7]
-       Use Continuous tag: 20181129-2118
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_UPDATE stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_CONFIGURE stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_BUILD stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Running CTEST_TEST stage...
-    Test project /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
+    Source directory: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
+    Build directory: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
+    Track: Continuous
+    Reading ctest configuration file: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test/CTestConfig.cmake
+    Site: JRM-macOS-DOE.local.dhcp.lbl.gov
+    Build name: [Darwin macOS 10.14.2 x86_64] [Python 3.7.0]
+    Use Continuous tag: 20190116-2239
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_UPDATE stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_CONFIGURE stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_BUILD stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Running CTEST_TEST stage...
+    Test project /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
         Start 1: list_directory
     1/2 Test #1: list_directory ...................   Passed    0.00 sec
         Start 2: hostname
@@ -314,8 +332,8 @@ without any configuration, build, etc. steps
     100% tests passed, 0 tests failed out of 2
 
     Total Test time (real) =   0.01 sec
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_COVERAGE stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_MEMCHECK stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_SUBMIT stage...
-    -- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Finished Continuous Stages (Start;Update;Configure;Build;Test;Coverage;MemCheck)
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_COVERAGE stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_MEMCHECK stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_SUBMIT stage...
+    -- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Finished Continuous Stages (Start;Update;Configure;Build;Test;Coverage;MemCheck)
 
diff --git a/docs/environment.yaml b/docs/environment.yaml
@@ -1,7 +1,7 @@
 name: docs
 channels:
-  - jrmadsen
   - conda-forge
+  - jrmadsen
   - defaults
 dependencies:
   - python=3.7

diff --git a/docs/index.rst b/docs/index.rst
@@ -19,14 +19,30 @@ Build Status
 .. image:: https://ci.appveyor.com/api/projects/status/p7m76ovx7sg781pf/branch/master?svg=true
    :target: https://ci.appveyor.com/project/jrmadsen/pyctest/branch/master
 
-########
-Anaconda
-########
+######################
+Anaconda (conda-forge)
+######################
 
-.. image:: https://anaconda.org/jrmadsen/pyctest/badges/version.svg
+.. image:: https://img.shields.io/badge/recipe-pyctest-green.svg
+   :target: https://anaconda.org/conda-forge/pyctest
+
+.. image:: https://img.shields.io/conda/vn/conda-forge/pyctest.svg
+   :target: https://anaconda.org/conda-forge/pyctest
+
+.. image:: https://img.shields.io/conda/pn/conda-forge/pyctest.svg
+   :target: https://anaconda.org/conda-forge/pyctest
+
+.. image:: https://img.shields.io/conda/dn/conda-forge/pyctest.svg
+   :target: https://anaconda.org/conda-forge/pyctest
+
+###################
+Anaconda (jrmadsen)
+###################
+
+.. image:: https://img.shields.io/badge/recipe-pyctest-green.svg
    :target: https://anaconda.org/jrmadsen/pyctest
 
-.. image:: https://anaconda.org/jrmadsen/pyctest/badges/latest_release_date.svg
+.. image:: https://anaconda.org/jrmadsen/pyctest/badges/version.svg
    :target: https://anaconda.org/jrmadsen/pyctest
 
 .. image:: https://anaconda.org/jrmadsen/pyctest/badges/platforms.svg

diff --git a/docs/install.rst b/docs/install.rst
@@ -10,20 +10,17 @@ This section covers the basics of how to download and install PyCTest.
 Supported Environments
 ======================
 
-PyCTest is tested, built, and distributed for python 2.7 3.5 3.6 on Linux/macOS
-and python 3.5 3.6 on Windows 10.
+PyCTest is tested, built, and distributed for python 2.7, 3.6, and 3.7 on Linux/macOS through conda-forge.
+Windows support is possible but Anaconda compiler issues within conda-forge with respect to ``std::unique_ptr``
+are currently causing issues.
 
 Installing from Conda (Recommended)
 ===================================
 
-If you only want to run PyCTest, not develop it, then you should install through
-a package manager. Conda, our supported package manager, can install PyCTest and
-its dependencies for you.
-
 First, you must have `Conda <http://continuum.io/downloads>`_ installed,
 then open a terminal or a command prompt window and run::
 
-    $ conda install -c conda-forge PyCTest
+    $ conda install -c conda-forge pyctest
 
 This will install PyCTest and all the dependencies from the conda-forge channel.
 
@@ -33,13 +30,13 @@ Updating the installation
 PyCTest is an active project, so we suggest you update your installation
 frequently. To update the installation run::
 
-    $ conda update -c conda-forge PyCTest
+    $ conda update -c conda-forge pyctest
 
 For some more information about using Conda, please refer to the
 `docs <http://conda.pydata.org/docs>`__.
 
-Installing from source with Conda
-=================================
+Installing from source
+======================
 
 Sometimes an adventurous user may want to get the source code, which is
 always more up-to-date than the one provided by Conda (with more bugs of
@@ -53,31 +50,51 @@ terminal and running::
     $ git clone https://github.com/jrmadsen/pyctest.git
 
 in the folder where you want the source code. This will create a folder called
-`PyCTest` which contains a copy of the source code.
+`pyctest` which contains a copy of the source code.
 
+Source installation is also available through `PyPi <https://pypi.org/project/pyctest/>`_::
+
+    $ pip install -vvv pyctest
 
 Installing dependencies
 -----------------------
 
-You will need to install all the dependencies listed in
-``requirements.txt`` or ``meta.yaml`` files. For example, requirements can be
-installed using Conda by running::
+You will need a C compiler, C++ compiler, CMake, Git, OpenSSL, and Curl
+on your system. Generally, these packages already exist on your system. The C++
+compiler requires support for C++11, in particular it needs to support lambdas and
+``std::unique_ptr``.
 
-    $ conda install --file requirements.txt
+After navigating to inside the `pyctest` directory, you can install PyCTest by
+building/compiling the shared libraries and either of the following standard Python
+installation commands:
 
-After navigating to inside the `PyCTest` directory, you can install PyCTest by
-building/compiling the shared libraries and running the install script::
+.. code:: shell
 
-    $ python build.py
-    $ pip install .
+    $ pip install -vvv .
+    $ python setup.py install
 
 Common issues
 -------------
 
-No issues with the current build system have been reported.
+- Lack of full C++11 support, particularly `std::unique_ptr`
 
 Importing PyCTest
 =================
 
-When importing, it is best to import PyCTest before importing numpy.
-See `this thread <https://github.com/jrmadsen/pyctest/issues/178>`_ for details.
+In general, the base module is not utilized directly. The following import scheme is generally simplest:
+
+   .. code:: python
+
+        import pyctest as _pyctest
+        import pyctest.pyctest as pyctest
+        import pyctest.pycmake as pycmake
+        import pyctest.helpers as helpers
+        from pyctest.cmake import CMake
+        from pyctest.ctest import CTest
+        from pyctest.cpack import CPack
+
+        print(_pyctest.version)
+        CMake('--version')
+        CTest('--version')
+        CPack('--version')
+