Start development of new doctests

actions/tests/test_actions.py

@@ -38,9 +38,8 @@ class ActionTestCase(unittest.TestCase):
         Convenience stuff for action testing.
         """
         # Determining the pm binary to be called. Going hard-coded is a bad
-        # thing. But this is a unit test and we now where we are. Also be
-        # putting it into the 'setUp' function, we only need to change it once,
-        # if so. The other idea would be to use a config file which
+        # thing. But this is a unit test and we know where we are as all unit
+        # tests are run in "tests/MODULENAME" within build-folder.
         bld_dir = os.path.abspath(os.path.dirname(os.path.dirname(os.getcwd())))
         self.pm_bin = os.path.join(bld_dir, 'stage', 'bin', 'pm')
         self.pm_action = None

cmake_support/doc/index.rst

@@ -114,8 +114,8 @@ Documentation
 
   .. code-block:: cmake
 
-                  add_doc_source(NAME name
-                                 DEP dependency1 [dependency2...])
+                  add_doc_dependency(NAME name
+                                     DEP dependency1 [dependency2...])
 
   Add a dependency to the doc build system. For an existing name, add some
   dependencies when it comes to building documentation. Mostly for internal use.

doc/CMakeLists.txt

@@ -168,3 +168,8 @@ endif()
 install(DIRECTORY ${_SPHINX_HTML_DIR} DESTINATION "share/promod3")
 # install man pages
 install(DIRECTORY ${_SPHINX_MAN_DIR} DESTINATION "share/promod3")
+
+# TODO (GT): remove doctest
+
+# add documentation tests
+add_subdirectory(tests)

doc/tests/CMakeLists.txt

+set(DOC_UNIT_TESTS
+  test_doctests.py
+)
+
+set(DOC_TEST_DATA
+  data/1crn.fasta
+  data/1crn_cut.pdb
+  scripts/modelling_all.py
+)
+
+promod3_unittest(MODULE doc
+  SOURCES "${DOC_UNIT_TESTS}"
+  DATA "${DOC_TEST_DATA}"
+)
+
+# TODO (GT): check what NAME to pass here!
+add_doc_dependency(NAME modelling
+                   DEP test_data_doc)

doc/tests/data/1crn.fasta

+>trg
+TTCCPSIVARSNFNVCRLPGTPEAICATYTGCIIIPGATCPGDYAN
+>tpl
+TTCCPSIVARSNFNVCRLPGTPEA------GCIIIPGATCPGDYAN

doc/tests/scripts/modelling_all.py

+from ost import io
+from promod3 import modelling
+
+# get raw model
+tpl = io.LoadPDB('data/1crn_cut.pdb')
+aln = io.LoadAlignment('data/1crn.fasta')
+aln.AttachView(1, tpl.CreateFullView())
+mhandle = modelling.BuildRawModel(aln)
+
+# build final model
+final_model = modelling.BuildFromRawModel(mhandle)
+io.SavePDB(final_model, 'model.pdb')
\ No newline at end of file

doc/tests/test_doctests.py

+"""
+Test example codes from documentation.
+Each example code is given as a python script in scripts-folder and may use
+data from data-folder.
+Scripts are executed with pm within BUILDFOLDER/tests/doc.
+Output of scripts shall be checked and cleaned up by caller.
+make target: test_doctests.py_run
+Don't forget to add new data-files and scripts to CMakeLists.txt!
+"""
+import unittest
+import os
+import subprocess
+from ost import io
+
+class DocTests(unittest.TestCase):
+    ################################################################
+    def compareLines(self, expected, actual):
+        '''Compare expected and actual, line-by-line ignoring whitespace.'''
+        lines_expected = expected.splitlines()
+        lines_actual = actual.splitlines()
+        self.assertEqual(len(lines_expected), len(lines_actual))
+        for (le, la) in zip(lines_expected, lines_actual):
+            self.assertEqual(le, la)
+
+    def checkPMRun(self, script_name, arguments=[], expect_rcode=0,
+                   expect_stdout=None, expect_stderr=None):
+        """
+        Run script with pm and test result.
+        :param script_name: Filename within script-folder to be called.
+        :param arguments:   List of strings of arguments to be passed.
+        :param expect_rcode:  Expected return code from call.
+        :param expect_stdout: Expected console output to stdout.
+        :param expect_stderr: Expected console output to stderr.
+        Note that ost-logs go to stderr by default!
+        For both expect_stdout and expect_stderr, None can be passed to ignore
+        console output. If given, it is checked line-by-line, while ignoring
+        whitespace for each line.
+        """
+        # get pm binary
+        bld_dir = os.path.abspath(os.path.dirname(os.path.dirname(os.getcwd())))
+        pm_bin = os.path.join(bld_dir, 'stage', 'bin', 'pm')
+        # launch it
+        script_path = os.path.join('scripts', script_name)
+        cmd = [pm_bin, script_path] + arguments
+        job = subprocess.Popen(cmd, stdout=subprocess.PIPE,
+                               stderr=subprocess.PIPE)
+        sout, serr = job.communicate()
+        # check return value
+        self.assertEqual(expect_rcode, job.returncode)
+        # check cmd.line-out if desired
+        if expect_stdout is not None:
+            self.compareLines(expect_stdout, sout)
+        if expect_stderr is not None:
+            self.compareLines(expect_stderr, serr)
+    ################################################################
+
+    def testModellingAll(self):
+        # run it
+        self.checkPMRun('modelling_all.py', [], 0)
+        # check that result exists and is readable
+        io.LoadPDB('model.pdb')
+        # clean up
+        os.remove('model.pdb')
+
+if __name__ == "__main__":
+    from ost import testutils
+    testutils.RunTests()

modelling/doc/index.rst

@@ -21,20 +21,9 @@ The last steps to go from a raw model to a final model can easily be executed
 with the :func:`BuildFromRawModel` function. In its simplest form, one can run
 a full protein homology modelling pipeline as follows:
 
-.. code-block:: python
-
-  from ost import io
-  from promod3 import modelling
+.. literalinclude:: ../../../tests/doc/scripts/modelling_all.py
 
-  # get raw model
-  tpl = io.LoadPDB('data/1crn_cut.pdb')
-  aln = io.LoadAlignment('data/1crn.fasta')
-  aln.AttachView(1, tpl.CreateFullView())
-  mhandle = modelling.BuildRawModel(aln)
-
-  # build final model
-  final_model = modelling.BuildFromRawModel(mhandle)
-  io.SavePDB(final_model, 'model.pdb')
+.. TODO (GT) .. literalinclude:: modelling_all.py
 
 If you want to run and tweak the internal steps, you can start with the 
 following code which is equivalent to the example above: