Tests: rebased and modified PR #180

.gitignore

@@ -22,7 +22,7 @@
 /doc/*.toc
 /doc/*.txt
 /doc/*Bib.xml
-/doc/*Bib.xml.bib
+/doc/*.xml.bib
 /doc/AutoDoc.xml
 /doc/_AutoDocMainFile.xml
 /doc/_Chapter*xml
@@ -32,3 +32,4 @@
 /doc/QuickReference/*
 /doc/title.xml
 VERSION
+*.actual/

CHANGES

@@ -3,6 +3,8 @@ This file describes changes in the AutoDoc package.
 YYYY.MM.DD
   - Scan bracket `\[\]` declarations correctly (PR #162)
   - Removed the hardcoded utf8 option, make it overrideable via gapdoc_latex_option
+  - Allow AutoDoc() to take absolute dirs and run from any dir (thanks to Glen Whitney)
+  - Add a test suite for AutoDoc (thanks to Glen Whitney)
 
 2018.02.14
   - Added @*Title commands to specify titles for Chapters etc.

PackageInfo.g

@@ -20,7 +20,7 @@ Subtitle := "Generate documentation from GAP source code",
 Version := Maximum( [
   "2018.07.03", ## Sebas' version
 ## This line prevents merge conflicts
-  "2016.12.04", ## Max' version
+  "2018.09.08", ## Max' version
 ## This line prevents merge conflicts
   "2013.11.01", ## Mohamed's version
 ] ),

gap/Magic.gi

@@ -73,8 +73,9 @@ end );
 InstallGlobalFunction( AutoDoc,
 function( arg )
     local pkgname, pkginfo, pkgdir,
-          opt, scaffold, gapdoc, maketest, autodoc,
+          opt, scaffold, gapdoc, maketest, autodoc, i,
           doc_dir, doc_dir_rel, tmp, key, val, file,
+          pkgdirstr, docdirstr,
           title_page, tree, is_worksheet,
           position_document_class, gapdoc_latex_option_record,
           makeDocFun, args;
@@ -135,7 +136,7 @@ function( arg )
         if IsEmpty( pkginfo ) then
             Error( "Could not find package ", pkgname );
         elif Length( pkginfo ) > 1 then
-            Info(InfoWarning, 1, "multiple versions of package ", pkgname, " are present, using the first one");
+            Info( InfoWarning, 1, "multiple versions of package ", pkgname, " are present, using the first one" );
         fi;
         pkginfo := pkginfo[ 1 ];
         pkgdir := Directory( pkginfo.InstallationPath );
@@ -172,11 +173,19 @@ function( arg )
         #   DirectoriesPackageLibrary( pkgname, "doc" )
         # because it returns an empty list if the subdirectory is missing.
         # But we want to handle that case by creating the directory.
-        doc_dir := Filename(pkgdir, doc_dir);
-        doc_dir := Directory(doc_dir);
+        doc_dir := Filename( pkgdir, doc_dir );
+        doc_dir := Directory( doc_dir );
 
     else
-        # TODO: doc_dir_rel = ... ?
+        # In this case, if doc_dir happens to lie below pkgdir, we want the
+        # doc_dir_rel to be the difference; if not we avoid binding doc_dir_rel
+        # and leave MakeGAPDocDoc to muddle through with absolute paths.
+        pkgdirstr := Filename( pkgdir, "" );
+        docdirstr := Filename( doc_dir, "" );
+        if StartsWith( docdirstr, pkgdirstr ) then
+            doc_dir_rel :=
+            Directory( docdirstr{[(Length(pkgdirstr)+1)..Length(docdirstr)]} );
+        fi;
     fi;
 
     # Ensure the output directory exists, create it if necessary
@@ -186,7 +195,7 @@ function( arg )
     # This helps diagnose problems where multiple instances of a package
     # are visible to GAP and the wrong one is used for generating the
     # documentation.
-    Print( "Generating documentation in ", doc_dir, "\n" );
+    Info( InfoGAPDoc, 1, "Generating documentation in ", doc_dir, "\n" );
 
     #
     # Extract scaffolding settings, which can be controlled via
@@ -252,6 +261,17 @@ function( arg )
             Append( autodoc.files, AUTODOC_FindMatchingFiles(pkgdir, autodoc.scan_dirs, [ "g", "gi", "gd", "autodoc" ]) );
         fi;
 
+        # Make sure all of the files exist, making the file names absolute if
+        # necessary
+        for i in [ 1 .. Length( autodoc.files ) ] do
+            if IsExistingFile( autodoc.files[ i ] ) then continue; fi;
+            if IsExistingFile( Filename( pkgdir, autodoc.files[ i ] ) ) then
+                autodoc.files[ i ] := Filename( pkgdir, autodoc.files[ i ] );
+                continue;
+            fi;
+            Error( autodoc.files[ i ], " does not specify an existing file either as an absolute path or relative to the package directory" );
+        od;
+
         if not IsBound( autodoc.level ) then
             autodoc.level := 0;
         fi;
@@ -322,14 +342,25 @@ function( arg )
         # will not work if there are any non-normalized paths in the list).
         gapdoc.files := Set( gapdoc.files );
 
-        # Convert the file paths in gapdoc.files, which are relative to
-        # the package directory, to paths which are relative to the doc directory.
-        # For this, we assume that doc_dir_rel is normalized (e.g.
-        # it does not contains '//') and relative.
-        # FIXME: this is an ugly hack, can't we do something better?
-        tmp := Number( Filename( doc_dir_rel, "" ), x -> x = '/' );
-        tmp := Concatenation( ListWithIdenticalEntries(tmp, "../") );
-        gapdoc.files := List( gapdoc.files, f -> Concatenation( tmp, f ) );
+        # If possible, convert the file paths in gapdoc.files, which are
+        # relative to the package directory, to paths which are relative to
+        # the doc directory.
+
+        if IsBound( doc_dir_rel ) then
+            # For this, we assume that doc_dir_rel is normalized (e.g.
+            # it does not contains '//') and relative.
+            # FIXME: this is an ugly hack, can't we do something better?
+            tmp := Number( Filename( doc_dir_rel, "" ), x -> x = '/' );
+            tmp := Concatenation( ListWithIdenticalEntries(tmp, "../") );
+            gapdoc.files := List( gapdoc.files, f -> Concatenation( tmp, f ) );
+        else
+            # Here presumably the doc_dir was given by an absolute path that
+            # does not lie below the package dir. In that case, we can't make
+            # the gapdoc.files relative to the doc dir, but rather we have no
+            # choice but to make them absolute, which MakeGAPDocDoc can handle,
+            # even if perhaps less gracefully/portably.
+            gapdoc.files := List( gapdoc.files, f -> Filename( pkgdir, f ) );
+        fi;
     fi;
 
 
@@ -515,7 +546,7 @@ function( arg )
             GAPDoc2LaTeXProcs.Tail );
 
         # Choose how we call GAPDoc
-        if Filename(DirectoriesSystemPrograms(), "pdflatex") <> fail then
+        if Filename( DirectoriesSystemPrograms(), "pdflatex" ) <> fail then
             makeDocFun := MakeGAPDocDoc;
         else
             makeDocFun := AutoDoc_MakeGAPDocDoc_WithoutLatex;

gap/ToolFunctions.gd

@@ -19,3 +19,5 @@ DeclareGlobalFunction( "AutoDoc_MakeGAPDocDoc_WithoutLatex" );
 DeclareGlobalFunction( "AutoDoc_CreatePrintOnceFunction" );
 
 DeclareGlobalFunction( "AUTODOC_Diff" );
+
+DeclareGlobalFunction( "AUTODOC_TestWorkSheet" );

gap/ToolFunctions.gi

@@ -237,3 +237,64 @@ function(args...)
     fi;
     return Process(DirectoryCurrent(), diff, InputTextUser(), OutputTextUser(), args);
 end);
+
+# AUTODOC_TestWorkSheet is used by AutoDocs test suite to test the worksheets
+# feature. Its single argument <ws> should be a string, and then
+# `tst/worksheets/<ws>` should be a directory containing a worksheet, and
+# `tst/worksheets/<ws>.expected` a directory containing the output of
+# AutoDocWorksheet for that worksheet.
+#
+# Then AUTODOC_TestWorkSheet will again run AutoDocWorksheet, put storing the
+# output into `tst/worksheets/<ws>.actual`; it then runs diff on all files in
+# order to find any differences that may have crept in. If no differences
+# exist, it outputs nothing.
+InstallGlobalFunction( AUTODOC_TestWorkSheet,
+function(ws)
+    local wsdir, sheetdir, expecteddir, actualdir, filenames, old, f, expected, actual;
+
+    # check worksheets dir exists
+    wsdir := DirectoriesPackageLibrary("AutoDoc", "tst/worksheets");
+    wsdir := wsdir[1];
+    if not IsDirectoryPath(wsdir) then
+      Error("could not access tst/worksheets/");
+    fi;
+
+    # check input dir exists
+    sheetdir := Filename(wsdir, Concatenation(ws, ".sheet"));
+    if not IsString(sheetdir) or not IsDirectoryPath(sheetdir) then
+      Error("could not access tst/", ws, ".sheet/");
+    fi;
+    sheetdir := Directory(sheetdir);
+
+    # check dir with expected output
+    expecteddir := Filename(wsdir, Concatenation(ws, ".expected"));
+    if not IsString(expecteddir) or not IsDirectoryPath(expecteddir) then
+      Error("could not access tst/", ws, ".expected/");
+    fi;
+    expecteddir := Directory(expecteddir);
+
+    # create and clear the output directory
+    actualdir := Filename(wsdir, Concatenation(ws, ".actual"));
+    Exec(Concatenation("rm -rf \"", actualdir, "\""));
+    AUTODOC_CreateDirIfMissing(actualdir);
+    actualdir := Directory(actualdir);
+
+    # Run the worksheet
+    filenames := DirectoryContents(sheetdir);
+    filenames := Filtered(filenames, f -> f <> "." and f <> "..");
+    filenames := List(filenames, f -> Filename(sheetdir, f));
+
+    old := InfoLevel(InfoGAPDoc);
+    SetInfoLevel(InfoGAPDoc, 0);
+    AutoDocWorksheet(filenames, rec(dir := actualdir));
+    SetInfoLevel(InfoGAPDoc, old);
+
+    # Check the results
+    filenames := DirectoryContents(expecteddir);
+    filenames := Filtered(filenames, f -> f <> "." and f <> "..");
+    for f in filenames do
+        expected := Filename(expecteddir, f);
+        actual := Filename(actualdir, f);
+        AUTODOC_Diff("-u", expected, actual);
+    od;
+end);

makedoc.g

@@ -28,5 +28,3 @@ AutoDoc(rec(
         )
     )
 ));
-
-QUIT;

scripts/build_gap.sh

@@ -28,32 +28,15 @@ make -j4 V=1
 
 # download packages; instruct wget to retry several times if the
 # connection is refused, to work around intermittent failures
-make bootstrap-pkg-minimal WGET="wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused"
-
-cd pkg
-
-wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused https://github.com/gap-packages/io/releases/download/v4.5.1/io-4.5.1.tar.bz2
-wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused https://github.com/gap-packages/Digraphs/releases/download/v0.12.0/digraphs-0.12.0.tar.gz
-wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused https://github.com/gap-packages/profiling/releases/download/v2.0.0/profiling-2.0.0.tar.gz
-wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused https://github.com/gap-packages/kbmag/releases/download/v1.5.5/kbmag-1.5.5.tar.gz
-wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused https://github.com/gap-packages/orb/releases/download/v4.8.0/orb-4.8.0.tar.bz2
-
-tar xvf io-*
-tar xvf digraphs-*
-tar xvf profiling-*
-tar xvf kbmag-*
-tar xvf orb-*
-
-
-git clone https://github.com/gap-packages/datastructures
+make bootstrap-pkg-full WGET="wget -N --no-check-certificate --tries=5 --waitretry=5 --retry-connrefused"
 
 # build some packages; default is to build 'io' and 'profiling', in order to
 # generate coverage results. If you need to build additional packages (or for
 # some reason need to build a custom version of io or profiling), please set
 # the GAP_PKGS_TO_BUILD environment variable (e.g. in your .travis.yml), or
 # directly call BuildPackages.sh from .travis.yml. For an example of the
 # former, take a look at the cvec package.
-
+cd pkg
 for pkg in ${GAP_PKGS_TO_BUILD-io profiling}; do
     ../bin/BuildPackages.sh --strict $pkg*
 done

tst/dogfood.tst

@@ -0,0 +1,59 @@
+#############################################################################
+##
+##  AutoDoc package
+##
+##  Test the behavior of AutoDoc by generating its own manual
+##
+##  Copyright 2018
+##    Contributed by Glen Whitney, studioinfinity.org
+##
+## Licensed under the GPL 2 or later.
+##
+#############################################################################
+
+gap> START_TEST( "dogfood.tst" );
+
+# need IO package for ChangeDirectoryCurrent
+gap> LoadPackage("io", false);
+true
+
+# temporarily change info levels to suppress all GAPDoc output
+gap> oldGAPDocLevel := InfoLevel( InfoGAPDoc );;
+gap> oldWarningLevel := InfoLevel( InfoWarning );;
+gap> SetInfoLevel( InfoGAPDoc, 0 );
+gap> SetInfoLevel( InfoWarning, 0 );
+
+# change into the package directory
+gap> olddir := AUTODOC_CurrentDirectory();;
+gap> pkgdir := DirectoriesPackageLibrary( "AutoDoc", "");;
+gap> ChangeDirectoryCurrent(Filename(pkgdir, ""));
+true
+
+# regenerate the manual using AutoDoc
+gap> Read("makedoc.g");
+
+# restore info levels and current director
+gap> SetInfoLevel( InfoGAPDoc, oldGAPDocLevel );
+gap> SetInfoLevel( InfoWarning, oldWarningLevel );
+gap> ChangeDirectoryCurrent(olddir);
+true
+
+# prepare to compare the output to the reference output
+# No point in testing chapters 1 or 2 unless/until they are converted to autodoc
+gap> docdir := DirectoriesPackageLibrary( "AutoDoc", "doc" );;
+gap> ex_dir := DirectoriesPackageLibrary( "AutoDoc", "tst/manual.expected" );;
+
+# check chapter 3
+gap> chap3 := Filename( docdir, "_Chapter_AutoDoc_worksheets.xml" );;
+gap> chap3ref := Filename( ex_dir, "_Chapter_AutoDoc_worksheets.xml" );;
+gap> AUTODOC_Diff("-u", chap3ref, chap3);
+0
+
+# check chapter 4
+gap> chap4 := Filename( docdir, "_Chapter_AutoDoc.xml" );;
+gap> chap4ref := Filename( ex_dir, "_Chapter_AutoDoc.xml" );;
+gap> AUTODOC_Diff("-u", chap4ref, chap4);
+0
+
+#
+gap> STOP_TEST( "dogfood.tst" );