GAP (AutoDoc) - Chapter 4: AutoDoc

Goto Chapter: Top 1 2 3 4 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

4 AutoDoc
4.1 The AutoDoc() function
4.1-1 AutoDoc
4.2 Examples

### 4 AutoDoc

#### 4.1 The AutoDoc() function

##### 4.1-1 AutoDoc

`‣ AutoDoc`( [packageOrDirectory][,] [optrec] ) | ( function )

Returns: nothing

This is the main function of the AutoDoc package. It can perform any combination of the following tasks:

1. 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 contents 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`.

2. 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.

3. 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:

packageOrDirectory

  The purpose of this parameter is twofold: to determine the package directory in which AutoDoc will operate, and to find the metadata concerning the package being documented. The parameter is either a string, an `IsDirectory` object, or omitted. If it is a string, AutoDoc interprets it as the name of a package, uses the metadata of the first package known to GAP with that name, and uses the `InstallationPath` specified in that metadata as the package directory. If packageOrDirectory is an `IsDirectory` object, this is used as package directory; if the argument is omitted, then the current directory is used. In the last two cases, the specified directory must contain a `PackageInfo.g` file, and AutoDoc extracts all needed metadata from that. The `IsDirectory` form 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.

  Note that when using `AutoDocWorksheet` (see 3.1), there is no parameter corresponding to packageOrDirectory and so the "package directory" is always the current directory, and there is no metadata.

optrec

  optrec can be a record with some additional options. The following are currently supported:

  dir

    This should either be a string, in which case it must be a path relative to the specified package directory, or a `Directory()` object. (Thus, the only way to designate an absolute directory is with a `Directory()` object.) This option specifies where the package documentation (e.g. the GAPDoc XML or the manual PDF, etc.) files are stored and/or will be generated.
    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",

                       rec( SomePackage := "<Package>SomePackage</Package>",
                            RELEASEYEAR := "2015" )

      then the following entity definitions are added to the XML preamble:

          <!ENTITY SomePackage '<Package>SomePackage</Package>'>
                       <!ENTITY RELEASEYEAR '2015'>

      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:

                       rec( Acknowledgements := "Many thanks to ..." )

      For a list of valid entries in the title page, please refer to the GAPDoc manual, specifically section GAPDoc: TitlePage.

    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.

  autodoc

    This controls whether and how to generate additional 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" ]`.

    LaTeXOptions

      Must be a record with entries which can be understood by `SetGapDocLaTeXOptions` (GAPDoc: 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.

    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 `MakeGAPDocDoc` (GAPDoc: MakeGAPDocDoc)

  extract_examples

    Either `true` or a record. If set to `true`, then all manual examples are extracted and placed into files `tst/PACKAGENAME01.tst`, `tst/PACKAGENAME02.tst`, ... and so on, with one file for each chapter. For chapters with no examples, no file is created.

    As a record, the entry can have the following entries itself, to specify some options.

    units

      This controls how examples are grouped into files. Recognized values are "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, one file is created for each chapter, each section, each subsection or each example. For all other values only a single file is created.

      On a technical level, AutoDoc passes the value to the units parameter of `ExtractExamples` (GAPDoc: ExtractExamples).

    skip_empty_in_numbering

      If set to `true` (the default), the generated files use filenames with strictly sequential numbering; that means that if chapter 1 (or whatever units are being used) contains no examples but chapter 2 does, then the examples for chapter 2 are put into the file `tst/PACKAGENAME01.tst`. If this option is set to `false`, then the chapter numbers are used to generate the filenames; so the examples for chapter 2 would be put into the file `tst/PACKAGENAME02.tst`.

  maketest

    This option is deprecated. Please use `extract_examples` instead.

    Either `true` or a record. When it is `true`, a simple `maketest.g` file 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.

#### 4.2 Examples

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

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 Bib Ind

generated by GAPDoc2HTML