From fdb6f5324852a1bd91a545d9741cdfc6b6b9d2cf Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Thu, 30 Aug 2018 23:18:02 -0400 Subject: [PATCH 1/6] Allow AutoDoc() to take absolute dirs and run from any dir Allow AutoDoc() to succeed with a dir entry in the options record which consists of an IsDirectory() object with an absolute path. There are two steps to this change: First, some effort must be made to correctly compute doc_dir_rel under such a circumstance. This commit uses the approach that if the pkgdir is a prefix of the doc_dir, then doc_dir_rel is the remainder of the doc_dir when the pkgdir is eliminated. If doc_dir is absolute and pkgdir is not a prefix thereof, then there is no sensible value for doc_dir_rel. Therefore, the second step of this change must be to handle downstream the case that doc_dir_rel is not set. This commit attempts to do so by presuming in such a case that there is no way to convert the gapdoc.files to paths relative to the doc_dir, and instead converts them to absolute paths. It may be the case that this strategy produces non-portable documentation files, but at least MakeGAPDocDoc succeeds, and it seems to be the only alternative in such case. Finally, to address the need to test modifications to AutoDoc, this commit adds a tst/testall.g that compares the results of running AutoDoc on some worksheets with reference files for those worksheets. It also invokes a boilerplate TestDirectory() call for maximum flexibility in adding future tests. Those ingredients created the opportunity to test the generation of the AutoDoc manual itself, and so this commit adds another new test, tst/dogfood.tst, which compares the result of AutoDoc on itself with reference files. To support this self-test, the commit also had to change makedoc.g to allow the parameter record to be extracted by the test, and it had to allow AutoDoc itself to be run from an arbitrary directory, not just the package directory of the package being documented. A minor point: this commit changes the Print() of the output directory to an Info() call so that it can be suppressed, to ensure that test results will be independent of the directory structure on the testing machine. Resolves: #165. In addition, the testing portion of this pull request seems to contribute some progress toward #152 and/or #57. --- .gitignore | 3 +- gap/Magic.gi | 61 +++- makedoc.g | 14 +- tst/dogfood.tst | 62 ++++ tst/manual.expected/_Chapter_AutoDoc.xml | 321 ++++++++++++++++++ .../_Chapter_AutoDoc_worksheets.xml | 27 ++ .../general.expected/_Chapter_Test.xml | 18 + tst/worksheets/general.sheet/worksheet.g | 23 ++ 8 files changed, 507 insertions(+), 22 deletions(-) create mode 100644 tst/dogfood.tst create mode 100644 tst/manual.expected/_Chapter_AutoDoc.xml create mode 100644 tst/manual.expected/_Chapter_AutoDoc_worksheets.xml create mode 100644 tst/worksheets/general.expected/_Chapter_Test.xml create mode 100644 tst/worksheets/general.sheet/worksheet.g diff --git a/.gitignore b/.gitignore index 11cd5f6c..94b5b5b8 100644 --- a/.gitignore +++ b/.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/ diff --git a/gap/Magic.gi b/gap/Magic.gi index 887aaae0..47f29ecd 100644 --- a/gap/Magic.gi +++ b/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; diff --git a/makedoc.g b/makedoc.g index 51232403..b0679f5c 100644 --- a/makedoc.g +++ b/makedoc.g @@ -10,9 +10,7 @@ ## ############################################################################# -LoadPackage("AutoDoc"); - -AutoDoc(rec( +autodoc_args_rec := rec( autodoc := true, scaffold := rec( includes := [ "Tutorials.xml", @@ -24,9 +22,13 @@ AutoDoc(rec( """ ), entities := rec( io := "io", - PackageName := "PackageName" + PackageName := "PackageName", ) ) -)); +); -QUIT; +if not IsBound( AutoDoc_just_a_test ) or not AutoDoc_just_a_test then + LoadPackage( "AutoDoc" ); + AutoDoc( "AutoDoc", autodoc_args_rec ); + QUIT_GAP(); +fi; diff --git a/tst/dogfood.tst b/tst/dogfood.tst new file mode 100644 index 00000000..b86d5c2f --- /dev/null +++ b/tst/dogfood.tst @@ -0,0 +1,62 @@ +############################################################################# +## +## 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. +## +############################################################################# +#### Note: we set InfoWarning to 0 temporarily below because we have to +#### suppress a message from GAPDocManualLabFromSixFile +#### (which function is in the core lib/package.gi) + +gap> START_TEST( "AutoDoc package: dogfood.tst" ); +gap> tstdir := DirectoriesPackageLibrary( "AutoDoc", "tst" )[ 1 ];; +gap> if IsWritableFile( Filename( tstdir, "" ) ) then +> outdir := Directory( Filename( tstdir, "manual.actual" ) ); +> else outdir := DirectoryTemporary(); +> fi; +gap> if IsExistingFile( Filename( outdir, "" ) ) then +> for fn in DirectoryContents( outdir ) do RemoveFile( Filename ( outdir, fn ) ); +> od; fi; +gap> AUTODOC_CreateDirIfMissing( Filename( outdir, "" ) );; +gap> AutoDoc_just_a_test := true; +true +gap> mdf := Filename( DirectoriesPackageLibrary( "AutoDoc", "")[ 1 ], "makedoc.g" );; +gap> Read(mdf); +gap> autodoc_args_rec.dir := outdir;; +gap> docdir := DirectoriesPackageLibrary( "AutoDoc", "doc" )[ 1 ];; +gap> for fn in [ "Tutorials.xml", "Comments.xml", "bib.xml" ] do +> contents := ReadAll( InputTextFile( Filename( docdir, fn ) ) ); +> WriteAll( OutputTextFile( Filename( outdir, fn ), false ), contents ); +> od; +gap> SetInfoLevel( InfoGAPDoc, 0 ); +gap> SetInfoLevel( InfoWarning, 0 ); +gap> AutoDoc( "AutoDoc", autodoc_args_rec); +true +gap> SetInfoLevel( InfoWarning, 1 ); +gap> ex_dir := Directory( Filename( tstdir, "manual.expected" ) );; +gap> chap3 := Filename( outdir, "_Chapter_AutoDoc_worksheets.xml" );; +gap> chap3ref := Filename( ex_dir, "_Chapter_AutoDoc_worksheets.xml" );; +gap> chap3diffout := Filename( outdir, "chap3.diff");; +gap> command := Concatenation( "diff -s -c ", chap3ref, " ", chap3, " > ", chap3diffout );; +gap> Exec( command ); +gap> chap3diff := ReadAll( InputTextFile( chap3diffout ) );; +gap> chap3good := chap3diff = Concatenation( "Files ", chap3ref, " and ", chap3, " are identical\n" ); +true +gap> if not chap3good then Print( chap3diff ); fi; +gap> chap4 := Filename( outdir, "_Chapter_AutoDoc.xml" );; +gap> chap4ref := Filename( ex_dir, "_Chapter_AutoDoc.xml" );; +gap> chap4diffout := Filename( outdir, "chap4.diff");; +gap> command := Concatenation( "diff -s -c ", chap4ref, " ", chap4, " > ", chap4diffout );; +gap> Exec( command ); +gap> chap4diff := ReadAll( InputTextFile( chap4diffout ) );; +gap> chap4good := chap4diff = Concatenation( "Files ", chap4ref, " and ", chap4, " are identical\n" ); +true +gap> if not chap4good then Print( chap4diff ); fi; +gap> STOP_TEST( "dogfood.tst", 10000 ); +## No point in testing chapters 1 or 2 unless/until they are converted to autodoc diff --git a/tst/manual.expected/_Chapter_AutoDoc.xml b/tst/manual.expected/_Chapter_AutoDoc.xml new file mode 100644 index 00000000..72c30235 --- /dev/null +++ b/tst/manual.expected/_Chapter_AutoDoc.xml @@ -0,0 +1,321 @@ + + + + +AutoDoc + +
+The AutoDoc() function + + + + nothing + + +This is the main function of the &AutoDoc; package. It can perform +any combination of the following three tasks: + + +It can (re)generate a scaffold for your package manual. +That is, it can produce two XML files in &GAPDoc; format to be used as part +of your manual: First, a file named doc/PACKAGENAME.xml +(with your package's name substituted) which is used as +main XML file for the package manual, i.e. this file sets the +XML doctype and defines various XML entities, includes +other XML files (both those generated by &AutoDoc; as well +as additional files created by other means), tells &GAPDoc; +to generate a table of content and an index, and more. +Secondly, it creates a file doc/title.xml containing a title +page for your documentation, with information about your package +(name, description, version), its authors and more, based +on the data in your PackageInfo.g. + + +It can scan your package for &AutoDoc; based documentation (by using &AutoDoc; +tags and the Autodoc command. +This will +produce further XML files to be used as part of the package manual. + + +It can use &GAPDoc; to generate PDF, text and HTML (with +MathJaX enabled) documentation from the &GAPDoc; XML files it +generated as well as additional such files provided by you. For +this, it invokes +to convert the XML sources, and it also instructs &GAPDoc; to copy +supplementary files (such as CSS style files) into your doc directory +(see ). + + +For more information and some examples, please refer to Chapter . +

+The parameters have the following meanings: + +package + +This is either the name of package, or an IsDirectory object. +In the former case, &AutoDoc; uses the metadata of the first package +with that name known to &GAP;. In the latter case, it checks whether +the given directory contains a PackageInfo.g file, and extracts +all needed metadata from that. This is for example useful if you have +multiple versions of the package around and want to make sure the +documentation of the correct version is built. +

+If this argument is omitted, &AutoDoc; uses the DirectoryCurrent(). + +optrec + +optrec can be a record with some additional options. +The following are currently supported: + +dir + +This should be a string containing a (relative) path or a +Directory() object specifying where the package documentation +(i.e. the &GAPDoc; XML files) are stored. +
+Default value: "doc/". + +scaffold + +This controls whether and how to generate scaffold XML files +for the package documentation. +

+The value should be either true, false or a +record. If it is a record or true (the latter is +equivalent to specifying an empty record), then this feature is +enabled. It is also enabled if opt.scaffold is missing but the +package's info record in PackageInfo.g has an AutoDoc entry. +In all other cases (in particular if opt.scaffold is +false), scaffolding is disabled. +

+If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is +assumed to be a record, and its contents are used as default values for +the scaffold settings. +

+

+If opt.scaffold is a record, it may contain the following entries. +

+ +includes + +A list of XML files to be included in the body of the main XML file. +If you specify this list and also are using &AutoDoc; to document +your operations with &AutoDoc; comments, +you can add _AutoDocMainFile.xml to this list +to control at which point the documentation produced by &AutoDoc; +is inserted. If you do not do this, it will be added after the last +of your own XML files. + +index + +By default, the scaffold creates an index. If you do not want an index, +set this to false. + +appendix + +This entry is similar to opt.scaffold.includes but is used +to specify files to include after the main body of the manual, +i.e. typically appendices. + +bib + +The name of a bibliography file, in BibTeX or XML format. +If this key is not set, but there is a file doc/PACKAGENAME.bib +then it is assumed that you want to use this as your bibliography. + +entities + +A record whose keys are taken as entity names, set to the corresponding +(string) values. For example, if you pass the record SomePackage, +

SomePackage", +RELEASEYEAR := "2015" )]]> +then the following entity definitions are added to the XML preamble: +SomePackage'> +]]> +This allows you to write &SomePackage; and &RELEASEYEAR; +in your documentation, which will be replaced by respective values specified +in the entities definition. + +TitlePage + +A record whose entries are used to embellish the generated title page +for the package manual with extra information, such as a copyright +statement or acknowledgments. To this end, the names of the record +components are used as XML element names, and the values of the +components are outputted as content of these XML elements. For +example, you could pass the following record to set a custom +acknowledgements text: + +For a list of valid entries in the title page, please refer to the +&GAPDoc; manual, specifically section . + +MainPage + +If scaffolding is enabled, by default a main XML file is generated (this +is the file which contains the XML doctype and more). If you do not +want this (e.g. because you have a handwritten main XML file), but +still want &AutoDoc; to generate a title page for you, you can set this +option to false + +document_class + +Sets the document class of the resulting PDF. The value can either be a string +which has to be the name of the new document class, a list containing this string, or +a list of two strings. Then the first one has to be the document class name, the second one +the option string ( contained in [ ] ) in LaTeX. + +latex_header_file + +Replaces the standard header from &GAPDoc; completely with the header in this LaTeX file. +Please be careful here, and look at GAPDoc's latexheader.tex file for an example. + +gapdoc_latex_options + +Must be a record with entries which can be understood by SetGapDocLaTeXOptions. Each entry can be a string, which +will be given to &GAPDoc; directly, or a list containing of two entries: The first one must be the string "file", +the second one a filename. This file will be read and then its content is passed to &GAPDoc; as option with the name +of the entry. + + + +autodoc + +This controls whether and how to generate addition XML documentation files +by scanning for &AutoDoc; documentation comments. +

+The value should be either true, false or a +record. If it is a record or true (the latter is +equivalent to specifying an empty record), then this feature is +enabled. It is also enabled if opt.autodoc is missing but the +package depends (directly) on the &AutoDoc; package. +In all other cases (in particular if opt.autodoc is +false), this feature is disabled. +

+

+If opt.autodoc is a record, it may contain the following entries. +

+ +files + +A list of files (given by paths relative to the package directory) +to be scanned for &AutoDoc; documentation comments. +Usually it is more convenient to use autodoc.scan_dirs, see below. + +scan_dirs + +A list of subdirectories of the package directory (given as relative paths) +which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files +are then scanned for &AutoDoc; documentation comments. +
+Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. + +level + +This defines the level of the created documentation. The default value is 0. +When parts of the manual are declared with a higher value +they will not be printed into the manual. + + + +gapdoc + +This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text +files from your various XML files. +

+The value should be either true, false or a +record. If it is a record or true (the latter is +equivalent to specifying an empty record), then this feature is +enabled. It is also enabled if opt.gapdoc is missing. +In all other cases (in particular if opt.gapdoc is +false), this feature is disabled. +

+

+If opt.gapdoc is a record, it may contain the following entries. +

+ +main + +The name of the main XML file of the package manual. +This exists primarily to support packages with existing manual +which use a filename here which differs from the default. +In particular, specifying this is unnecessary when using scaffolding. +
+Default value: PACKAGENAME.xml. + +files + +A list of files (given by paths relative to the package directory) +to be scanned for &GAPDoc; documentation comments. +Usually it is more convenient to use gapdoc.scan_dirs, see below. + +scan_dirs + +A list of subdirectories of the package directory (given as relative paths) +which &AutoDoc; then scans for .gi, .gd and .g files; all of these files +are then scanned for &GAPDoc; documentation comments. +
+Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. + +gap_root_relative_path + +Either a boolean, or a string containing a relative path. +By default (if this option is not set, or is set to false), +references in the generated documentation referring to external documentation +(such as the GAP manual) are encoded using absolute paths. +This is fine as long as the documentation stays on only a single +computer, but is problematic when preparing documentation that should be +used on multiple computers, e.g., when creating a distribution archive of +a GAP package.
+Thus, if a relative path is provided via this option (or if it is set to true, +in which case the relative path ../../.. is used), then &AutoDoc; +and &GAPDoc; attempt to replace all absolute paths in references to GAP +manuals by paths based on this relative path.

+

+On a technical level, &AutoDoc; passes the relative path to the +gaproot parameter of

+ + + +maketest + +The maketest item can be true or a record. When it is true, +a simple maketest.g is created in the main package directory, +which can be used to test the examples from the manual. As a record, +the entry can have the following entries itself, to specify some options. + +filename + +Sets the name of the test file. + +commands + +A list of strings, each one a command, which +will be executed at the beginning of the test file. + + + + + + +

+ + + + +

+ + +
+Examples + +

+Some basic examples for using AutoDoc were already shown in +Chapter . +

+ + + + diff --git a/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml b/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml new file mode 100644 index 00000000..e089480f --- /dev/null +++ b/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml @@ -0,0 +1,27 @@ + + + + +AutoDoc worksheets + +
+Worksheets + + + + +The intention of these function is to create stand-alone pdf and html files +using AutoDoc without having them associated to a package. +It uses the same optional records as the &AutoDoc; command itself, but instead of +a package name there should be a filename or a list of filenames containing AutoDoc +text from which the documents are created. Please see the &AutoDoc; command for more +information about this and have a look at for a simple worksheet example. + + + + +
+ + + + diff --git a/tst/worksheets/general.expected/_Chapter_Test.xml b/tst/worksheets/general.expected/_Chapter_Test.xml new file mode 100644 index 00000000..001947a6 --- /dev/null +++ b/tst/worksheets/general.expected/_Chapter_Test.xml @@ -0,0 +1,18 @@ + + + + +Test + +This is dummy text + S5 := SymmetricGroup(5); +Sym( [ 1 .. 5 ] ) +gap> Size(S5); +120 +]]> + + +And we wrap up with some dummy text + + diff --git a/tst/worksheets/general.sheet/worksheet.g b/tst/worksheets/general.sheet/worksheet.g new file mode 100644 index 00000000..72c7320a --- /dev/null +++ b/tst/worksheets/general.sheet/worksheet.g @@ -0,0 +1,23 @@ +############################################################################# +## +## AutoDoc package +## +## Copyright 2018 +## Contributed by Glen Whitney, studioinfinity.org +## +## Licensed under the GPL 2 or later. +## +############################################################################# +Print( "Pretend this is a code file.\n" ); +Print( "(Even though we never use it that way.\n" ); +#! @Title General Test +#! @Date 2018/08/30 +#! @Chapter Test +#! This is dummy text +#! @BeginExampleSession +#! gap> S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +#! gap> Size(S5); +#! 120 +#! @EndExampleSession +#! And we wrap up with some dummy text From a51479a9e50a613080ca964a8ad5fb70d35dea97 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 7 Sep 2018 22:08:33 +0200 Subject: [PATCH 2/6] Rewrite worksheets testing code --- gap/ToolFunctions.gd | 2 ++ gap/ToolFunctions.gi | 61 ++++++++++++++++++++++++++++++++++++++++++++ tst/worksheets.tst | 10 ++++++++ 3 files changed, 73 insertions(+) create mode 100644 tst/worksheets.tst diff --git a/gap/ToolFunctions.gd b/gap/ToolFunctions.gd index 26175e20..7250a32a 100644 --- a/gap/ToolFunctions.gd +++ b/gap/ToolFunctions.gd @@ -19,3 +19,5 @@ DeclareGlobalFunction( "AutoDoc_MakeGAPDocDoc_WithoutLatex" ); DeclareGlobalFunction( "AutoDoc_CreatePrintOnceFunction" ); DeclareGlobalFunction( "AUTODOC_Diff" ); + +DeclareGlobalFunction( "AUTODOC_TestWorkSheet" ); diff --git a/gap/ToolFunctions.gi b/gap/ToolFunctions.gi index 68255413..c90f7284 100644 --- a/gap/ToolFunctions.gi +++ b/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 should be a string, and then +# `tst/worksheets/` should be a directory containing a worksheet, and +# `tst/worksheets/.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/.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); diff --git a/tst/worksheets.tst b/tst/worksheets.tst new file mode 100644 index 00000000..3606033d --- /dev/null +++ b/tst/worksheets.tst @@ -0,0 +1,10 @@ +# +# test worksheets +# +gap> START_TEST( "worksheets.tst" ); + +# +gap> AUTODOC_TestWorkSheet("general"); + +# +gap> STOP_TEST( "worksheets.tst" ); From 0992389505dda78b860f7ea8d0d644377e36b154 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 7 Sep 2018 22:02:28 +0200 Subject: [PATCH 3/6] Rewrite dogfood.tst --- makedoc.g | 14 +++----- tst/dogfood.tst | 85 ++++++++++++++++++++++++------------------------- 2 files changed, 46 insertions(+), 53 deletions(-) diff --git a/makedoc.g b/makedoc.g index b0679f5c..1c5e7961 100644 --- a/makedoc.g +++ b/makedoc.g @@ -10,7 +10,9 @@ ## ############################################################################# -autodoc_args_rec := rec( +LoadPackage("AutoDoc"); + +AutoDoc(rec( autodoc := true, scaffold := rec( includes := [ "Tutorials.xml", @@ -22,13 +24,7 @@ autodoc_args_rec := rec( """ ), entities := rec( io := "io", - PackageName := "PackageName", + PackageName := "PackageName" ) ) -); - -if not IsBound( AutoDoc_just_a_test ) or not AutoDoc_just_a_test then - LoadPackage( "AutoDoc" ); - AutoDoc( "AutoDoc", autodoc_args_rec ); - QUIT_GAP(); -fi; +)); diff --git a/tst/dogfood.tst b/tst/dogfood.tst index b86d5c2f..f256b01e 100644 --- a/tst/dogfood.tst +++ b/tst/dogfood.tst @@ -10,53 +10,50 @@ ## Licensed under the GPL 2 or later. ## ############################################################################# -#### Note: we set InfoWarning to 0 temporarily below because we have to -#### suppress a message from GAPDocManualLabFromSixFile -#### (which function is in the core lib/package.gi) - -gap> START_TEST( "AutoDoc package: dogfood.tst" ); -gap> tstdir := DirectoriesPackageLibrary( "AutoDoc", "tst" )[ 1 ];; -gap> if IsWritableFile( Filename( tstdir, "" ) ) then -> outdir := Directory( Filename( tstdir, "manual.actual" ) ); -> else outdir := DirectoryTemporary(); -> fi; -gap> if IsExistingFile( Filename( outdir, "" ) ) then -> for fn in DirectoryContents( outdir ) do RemoveFile( Filename ( outdir, fn ) ); -> od; fi; -gap> AUTODOC_CreateDirIfMissing( Filename( outdir, "" ) );; -gap> AutoDoc_just_a_test := true; + +gap> START_TEST( "dogfood.tst" ); + +# need IO package for ChangeDirectoryCurrent +gap> LoadPackage("io", false); true -gap> mdf := Filename( DirectoriesPackageLibrary( "AutoDoc", "")[ 1 ], "makedoc.g" );; -gap> Read(mdf); -gap> autodoc_args_rec.dir := outdir;; -gap> docdir := DirectoriesPackageLibrary( "AutoDoc", "doc" )[ 1 ];; -gap> for fn in [ "Tutorials.xml", "Comments.xml", "bib.xml" ] do -> contents := ReadAll( InputTextFile( Filename( docdir, fn ) ) ); -> WriteAll( OutputTextFile( Filename( outdir, fn ), false ), contents ); -> od; + +# 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 ); -gap> AutoDoc( "AutoDoc", autodoc_args_rec); + +# change into the package directory +gap> olddir := AUTODOC_CurrentDirectory();; +gap> pkgdir := DirectoriesPackageLibrary( "AutoDoc", "");; +gap> ChangeDirectoryCurrent(Filename(pkgdir, "")); true -gap> SetInfoLevel( InfoWarning, 1 ); -gap> ex_dir := Directory( Filename( tstdir, "manual.expected" ) );; -gap> chap3 := Filename( outdir, "_Chapter_AutoDoc_worksheets.xml" );; -gap> chap3ref := Filename( ex_dir, "_Chapter_AutoDoc_worksheets.xml" );; -gap> chap3diffout := Filename( outdir, "chap3.diff");; -gap> command := Concatenation( "diff -s -c ", chap3ref, " ", chap3, " > ", chap3diffout );; -gap> Exec( command ); -gap> chap3diff := ReadAll( InputTextFile( chap3diffout ) );; -gap> chap3good := chap3diff = Concatenation( "Files ", chap3ref, " and ", chap3, " are identical\n" ); + +# 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 -gap> if not chap3good then Print( chap3diff ); fi; -gap> chap4 := Filename( outdir, "_Chapter_AutoDoc.xml" );; + +# 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> chap4diffout := Filename( outdir, "chap4.diff");; -gap> command := Concatenation( "diff -s -c ", chap4ref, " ", chap4, " > ", chap4diffout );; -gap> Exec( command ); -gap> chap4diff := ReadAll( InputTextFile( chap4diffout ) );; -gap> chap4good := chap4diff = Concatenation( "Files ", chap4ref, " and ", chap4, " are identical\n" ); -true -gap> if not chap4good then Print( chap4diff ); fi; -gap> STOP_TEST( "dogfood.tst", 10000 ); -## No point in testing chapters 1 or 2 unless/until they are converted to autodoc +gap> AUTODOC_Diff("-u", chap4ref, chap4); +0 + +# +gap> STOP_TEST( "dogfood.tst" ); From cff1db8a4a3f0eff235967c69057f3a0bccc51ae Mon Sep 17 00:00:00 2001 From: Max Horn Date: Sat, 8 Sep 2018 16:52:29 +0200 Subject: [PATCH 4/6] Update package version --- PackageInfo.g | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PackageInfo.g b/PackageInfo.g index a62b5556..4c3b8805 100644 --- a/PackageInfo.g +++ b/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 ] ), From 52b4d8b708a0554d6dd43205bb1c0807c0176dea Mon Sep 17 00:00:00 2001 From: Max Horn Date: Mon, 10 Sep 2018 13:34:37 +0200 Subject: [PATCH 5/6] Update CHANGES --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 6ca3bd99..0782d53c 100644 --- a/CHANGES +++ b/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. From de1948401d62d58a3dc47738c18be460f4caa2e8 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Wed, 12 Sep 2018 01:29:00 +0200 Subject: [PATCH 6/6] Update Travis scripts --- scripts/build_gap.sh | 21 ++----------- scripts/travis-build.sh | 68 ----------------------------------------- scripts/travis-test.sh | 8 ----- 3 files changed, 2 insertions(+), 95 deletions(-) delete mode 100755 scripts/travis-build.sh delete mode 100755 scripts/travis-test.sh diff --git a/scripts/build_gap.sh b/scripts/build_gap.sh index c17a7737..35a9fdc1 100755 --- a/scripts/build_gap.sh +++ b/scripts/build_gap.sh @@ -28,24 +28,7 @@ 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 @@ -53,7 +36,7 @@ git clone https://github.com/gap-packages/datastructures # 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 diff --git a/scripts/travis-build.sh b/scripts/travis-build.sh deleted file mode 100755 index 0a9c869c..00000000 --- a/scripts/travis-build.sh +++ /dev/null @@ -1,68 +0,0 @@ -# If a command fails, exit this script with an error code -set -e - -# Store this directory -PKGDIR=$(pwd) - -# Download and compile GAP -cd .. -echo -en 'travis_fold:start:InstallGAP\r' -git clone -b $GAP_BRANCH --depth=1 https://github.com/$GAP_FORK/gap.git -cd gap -./configure --with-gmp=system $GAP_FLAGS -make -mkdir pkg -cd .. -echo -en 'travis_fold:end:InstallGAP\r' - -# Compile the Digraphs package -echo -en 'travis_fold:start:InstallANATPH\r' -mv $PKGDIR gap/pkg/anatph -echo -en 'travis_fold:end:InstallANATPH\r' - -cd gap - -# Get the packages -echo -en 'travis_fold:start:InstallPackages\r' -cd pkg -echo -en 'travis_fold:start:$GAPDOC\r' -curl -O http://www.gap-system.org/pub/gap/gap4/tar.gz/packages/$GAPDOC.tar.gz -tar xzf $GAPDOC.tar.gz -rm $GAPDOC.tar.gz -echo -en 'travis_fold:end:$GAPDOC\r' -echo -en 'travis_fold:start:$PROFILING\r' -curl -O http://www.gap-system.org/pub/gap/gap4/tar.gz/packages/$PROFILING.tar.gz -tar xzf $PROFILING.tar.gz -rm $PROFILING.tar.gz -cd $PROFILING -./configure $PKG_FLAGS -make -cd .. -echo -en 'travis_fold:end:$PROFILING\r' -echo -en 'travis_fold:end:$IO\r' -curl -O http://www.gap-system.org/pub/gap/gap4/tar.gz/packages/$IO.tar.gz -tar xzf $IO.tar.gz -rm $IO.tar.gz -cd $IO -./configure $PKG_FLAGS -make -cd .. -echo -en 'travis_fold:end:$IO\r' -echo -en 'travis_fold:end:$ORB\r' -curl -O http://www.gap-system.org/pub/gap/gap4/tar.gz/packages/$ORB.tar.gz -tar xzf $ORB.tar.gz -rm $ORB.tar.gz -cd $ORB -./configure $PKG_FLAGS -make -cd .. -echo -en 'travis_fold:end:$ORB\r' -echo -en 'travis_fold:end:$DIGRAPHS\r' -curl -O http://www.gap-system.org/pub/gap/gap4/tar.gz/packages/$DIGRAPHS.tar.gz -tar xzf $DIGRAPHS.tar.gz -cd $DIGRAPHS -./configure $PKG_FLAGS -make -cd ../../.. -echo -en 'travis_fold:end:$DIGRAPHS\r' -echo -en 'travis_fold:end:InstallPackages\r' diff --git a/scripts/travis-test.sh b/scripts/travis-test.sh deleted file mode 100755 index a4b39e9d..00000000 --- a/scripts/travis-test.sh +++ /dev/null @@ -1,8 +0,0 @@ -# If a command fails, exit this script with an error code -set -e - -echo -en 'travis_fold:start:RunTests\r' -cd ../.. -echo "LoadPackage(\"anatph\"); AnatphTestStandard(); quit; quit; quit;" | bin/gap.sh -A -r -m 1g -T 2>&1 | tee testlog.txt -echo -en 'travis_fold:end:RunTests\r' -( ! grep -E "########> Diff|brk>|#E|Error|# WARNING|fail|Syntax warning" testlog.txt )