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/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. 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 ] ), 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/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/makedoc.g b/makedoc.g index 51232403..1c5e7961 100644 --- a/makedoc.g +++ b/makedoc.g @@ -28,5 +28,3 @@ AutoDoc(rec( ) ) )); - -QUIT; 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 ) diff --git a/tst/dogfood.tst b/tst/dogfood.tst new file mode 100644 index 00000000..f256b01e --- /dev/null +++ b/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" ); 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.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" ); 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