‣ AutoDoc ( package_name[, option_record] ) | ( function ) |
Returns: 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 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 MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc) to convert the XML sources, and it also instructs GAPDoc to copy supplementary files (such as CSS style files) into your doc directory (see CopyHTMLStyleFiles
(GAPDoc: CopyHTMLStyleFiles)).
For more information and some examples, please refer to Chapter 1.
The parameters have the following meanings:
The name of the package whose documentation should be(re)generated.
option_record can be a record with some additional options. The following are currently supported:
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/"
.
This controls whether and how to generate scaffold XML files for the main and title page of the package's 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 opt.scaffold is a record, it may contain the following entries.
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.
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.
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.
A record whose entries are used to embellish the generated titlepage 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:
rec( Acknowledgements := "Many thanks to ..." )
For a list of valid entries in the titlepage, please refer to the GAPDoc manual, specifically section GAPDoc: Title and following.
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.
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.
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.
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.
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.
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 AutoDoc documentation comments.
Default value: [ "gap", "lib", "examples", "examples/doc" ]
.
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.
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.
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
.
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.
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" ]
.
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.
Sets the name of the test file.
A list of strings, each one a command, which will be executed at the beginning of the test file.
generated by GAPDoc2HTML