Getting started using &AutoDoc;

This chapter gives practical workflows for adding &AutoDoc; to a package. For a high-level feature overview and adoption strategy, see chapter .

Choose your workflow

You can use &AutoDoc; in several ways, and it is fine to combine them: Start a new package manual from scratch (Section ). Integrate &AutoDoc; into an existing &GAPDoc; manual (Section ). Use only selected features, such as title-page generation or example extraction, while keeping everything else unchanged.

This incremental approach is encouraged: start with the smallest helpful step, then adopt additional features when useful.
Creating a package manual from scratch

Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a scaffold for a package manual using the command like this:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( scaffold := true ) );

When called from a file such as makedoc.g, &AutoDoc; uses the directory containing that file as the package directory. Otherwise, it falls back to the current directory. In either case it then reads the PackageInfo.g file from that package directory. It extracts information about the package from it (such as its name and version, see Section ). It then creates two XML files doc/_main.xml and doc/title.xml inside the package directory. Finally, it runs &GAPDoc; on them to produce a nice initial PDF and HTML version of your fresh manual.

To ensure that the &GAP; help system picks up your package manual, you should also add something like the following to your PackageInfo.g:

    PackageDoc := rec(
      BookName  := ~.PackageName,
      ArchiveURLSubset := ["doc"],
      HTMLStart := "doc/chap0.html",
      PDFFile   := "doc/manual.pdf",
      SixFile   := "doc/manual.six",
      LongTitle := ~.Subtitle,
    ),

Congratulations, your package now has a minimal working manual. Of course it will be mostly empty for now, but it already should contain some useful information, based on the data in your PackageInfo.g. This includes your package's name, version and description as well as information about its authors. And if you ever change the package data, (e.g. because your email address changed), just re-run the above command to regenerate the two main XML files with the latest information.

Next of course you need to provide actual content (unfortunately, we were not yet able to automate that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further &GAPDoc; XML files containing extra chapters, sections and so on. Or you could use classic &GAPDoc; source comments. For details on either, please refer to , as well as Section of this manual on how to teach the command to include this extra documentation. Or you could use the special documentation facilities &AutoDoc; provides (see Section ).

You will probably want to re-run the command frequently, e.g. whenever you modified your documentation or your PackageInfo.g. To make this more convenient and reproducible, we recommend putting its invocation into a file makedoc.g in your package makedoc.g directory, with content based on the following example:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := true ) );
    QUIT;

Then you can regenerate the package manual from the command line with the following command:

    gap makedoc.g

If you also want regression tests from your manual examples, enable extract_examples := true; this is explained in Section .

Documenting code with &AutoDoc;

&AutoDoc; supports several equally supported ways to organize your manual text. You can put chapter and section material directly into #! comments inside .g, .gd, or .gi files, you can put it into standalone .autodoc files, and you can mix either style with existing &GAPDoc; XML. Which arrangement is best is mostly a matter of taste and convenience. The detailed command reference for these styles is in chapter , especially Section .

To get one of your global functions, operations, attributes etc. to appear in the package manual, simply insert an &AutoDoc; comment of the form #! directly in front of it. For example:

    #!
    DeclareOperation( "ToricVariety", [ IsConvexObject ] );

This tiny change is already sufficient to ensure that the operation appears in the manual. In general, you will want to add further information about the operation, such as in the following example:

Important: the comment block must be immediately followed by the declaration it documents. Do not place other code between the comment block and the Declare... statement.

    #! @Arguments conv
    #! @Returns a toric variety
    #! @Description
    #!  Creates a toric variety out
    #!  of the convex object <A>conv</A>.
    DeclareOperation( "ToricVariety", [ IsConvexObject ] );

In these comment lines, you can freely use normal &GAPDoc; XML markup (with the usual exceptions for lines starting with @, which are interpreted as &AutoDoc; commands). So, for instance, tags like `<Ref>`, `<A>`, `<K>`, `<List>`, etc. can be written directly in #! comment text.

For chapter text, tutorial material, worked examples, and similar prose, some authors prefer to keep the material next to their code using #! @Chapter, #! @Section, and related commands, while others prefer standalone .autodoc files. In an .autodoc file you write the same commands without the #! prefix, and you list the file in autodoc.files or place it in a directory scanned via autodoc.scan_dirs. AutoDoc itself still uses the source-comment style in places, for example in gap/Magic.gd.

One caveat applies if you decide to keep prose in a standalone .autodoc file but want to interrupt it with the documentation of a declaration that is written in source comments. Today that requires the chunk mechanism, and that workflow is currently limited; see issue #60 in the AutoDoc issue tracker.

For a thorough description of what you can do with &AutoDoc; documentation comments, please refer to chapter .

Suppose you have not been using &GAPDoc; before but instead used the process described in section to create your manual. Then the following &GAP; command will regenerate the manual and automatically include all newly documented functions, operations etc.:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( scaffold := true,
                  autodoc := true ) );

If you are not using the scaffolding feature, e.g. because you already have an existing &GAPDoc; based manual, then you can still use &AutoDoc; documentation comments and standalone .autodoc files. Just make sure to first edit the main XML file of your documentation, and insert the line

    &lt;#Include SYSTEM "_AutoDocMainFile.xml">

in a suitable place. This means that you can mix &AutoDoc; documentation comments and .autodoc files freely with your existing documentation; you can even still make use of any existing &GAPDoc; documentation comments in your code.

The following command should be useful for you in this case; it still scans the package code for &AutoDoc; documentation comments and then runs &GAPDoc; to produce HTML and PDF output, but does not touch your documentation XML files otherwise.

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := true ) );

Using &AutoDoc; in an existing &GAPDoc; manual

Even if you already have an existing &GAPDoc; manual, it might be interesting for you to use &AutoDoc; for two purposes:

First, with &AutoDoc; it is very convenient to regenerate your documentation.

Secondly, the scaffolding feature which generates a title page with all the metadata of your package in a uniform way is very handy. The somewhat tedious process of keeping your title page in sync with your PackageInfo.g is fully automated this way (including the correct version, release data, author information and so on).

There are various examples of packages using &AutoDoc; for this purpose only, e.g. &io; and orb.

In particular, this setup works well if you want to keep your existing manual structure and only adopt selected &AutoDoc; features first; for example automatic title-page data and predefined entities such as &VERSION;, &RELEASEYEAR; and &RELEASEDATE; (see Section ).

Using &AutoDoc; on a complete &GAPDoc; manual

Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g, .gd, and .gi files. Suppose the main XML file is named PACKAGENAME.xml and is in the /doc subdirectory of your package. Then you can rebuild your manual by executing the following two &GAP; commands from a &GAP; session started in the root directory of your package:

    LoadPackage( "AutoDoc" );
    AutoDoc( );

Note that in particular, you do not have to worry about keeping a list of your implementation files up-to-date.

But there is more. &AutoDoc; can create .tst files from the examples in your manual to test your package. This can be achieved via

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( extract_examples := true ) );

Now files PACKAGENAME01.tst, PACKAGENAME02.tst and so appear in the tst/ subdirectory of your package, and can be tested as usual using respectively .

If you prefer to keep generated tests in a separate location, set extract_examples.subdir to a path relative to the package root:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( extract_examples := rec( subdir := "tst/generated" ) ) );

This writes the extracted examples into tst/generated/ instead.

Setting different &GAPDoc; options

Sometimes, the default values for the &GAPDoc; command used by &AutoDoc; may not be suitable for your manual.

Suppose your main XML file is not named PACKAGENAME.xml, but rather something else, e.g. main.xml. Then you can tell &AutoDoc; to use this file as the main XML file via

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( gapdoc := rec( main := "main" ) ) );

&AutoDoc; can scan directories for documentation input automatically. In fact there are two separate scanning steps. The option autodoc.scan_dirs controls where it looks for source comments beginning with #! and for standalone .autodoc files. By default, it scans the package root directory and the subdirectories gap, lib, examples and examples/doc; the listed subdirectories are scanned recursively, while the package root itself is only scanned at top level. If you keep that kind of input in other directories, adjust autodoc.scan_dirs. The following example instructs &AutoDoc; to only search in the subdirectory package_sources of the package's root directory for those files.

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );

The separate option gapdoc.scan_dirs serves a different purpose: it controls where &GAPDoc; comments are searched for.

You can also specify an explicit list of files containing documentation, which will be searched in addition to any files located within the scan directories:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );

Giving such a file does not prevent the standard scan_dirs from being scanned for other files.

Next, &GAPDoc; supports the documentation to be built with relative paths. This means, links to manuals of other packages or the &GAP; library will not be absolute, but relative from your documentation. This can be particularly useful if you want to build a release tarball or move your &GAP; installation around later. Suppose you are starting &GAP; in the root path of your package as always, and the standard call of will then build the documentation in the doc subdirectory of your package. From this directory, the gap root directory has the relative path ../../... Then you can enable the relative paths by

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );

or, since ../../.. is the standard option for gap_root_relative_path, by

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );

The same behavior is also available via the global option `relativePath`. This is particularly convenient in a short makedoc.g script, and it overrides `gapdoc.gap_root_relative_path` if both are given. Since this is a GAP global option, you can also set it outside the eventual call and let it propagate through nested calls; see for more information about GAP's global options system:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );

If you pass `relativePath := true`, then &AutoDoc; uses the default relative path ../../...

For example, if your makedoc.g reads the manual via , then the following command sets both `relativePath` and `nopdf` to true for that nested call:

    Read( "makedoc.g" : nopdf, relativePath );

Finally, if you only want HTML and text output, you can suppress PDF generation with the global option `nopdf`:

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( autodoc := true ) : nopdf );

This is useful if `pdflatex` is unavailable, or when you want a faster documentation rebuild while editing.

You can also request the same behavior from the shell by setting the environment variable `NOPDF` before invoking makedoc.g. For example:

    NOPDF=1 gap makedoc.g

If `NOPDF` is set, &AutoDoc; skips PDF generation even if no `nopdf` option is given in the GAP code.

Checklist for converting an existing &GAPDoc; manual to use &AutoDoc;

Here is a checklist for authors of a package &PackageName;, which already has a &GAPDoc; based manual, who wish to use &AutoDoc; to build the manual from now on. We assume that the manual is currently built by reading a file makedoc.g and that the main .xml file is named manual.xml.

The files PackageInfo.g, makedoc.g, doc/title.xml and doc/_main.xml (if it exists) will be altered by this procedure, so it may be wise to keep backup copies.

You should have copies of the &AutoDoc; files PackageInfo.g and makedoc.g to hand when reading these instructions.

Copy AutoDoc/makedoc.g to PackageName/makedoc.g. Edit PackageName/makedoc.g as follows. Change the header comment to match other files in your package. After `LoadPackage("AutoDoc");` add `LoadPackage("PackageName");`. In the `AutoDoc` record delete `autodoc := true;`. In the `scaffold` record change the `includes` list to be the list of your `.xml` files that are contained in manual.xml. If you do not have a bibliography you may delete the `bib := "bib.xml",` field in the scaffold. Otherwise, edit the file name if you have a different file. If you only have a `.bib` file (`manual.bib` or `bib.xml.bib` say) you should rename this file PackageName.bib. In the `LaTeXOptions` record, which is in the `gapdoc` record, enter any &LaTeX; `newcommands` previously in manual.xml. (If there are none you may safely delete this record.) To illustrate this option, the &AutoDoc; file makedoc.g defines the command `\bbZ` by `\newcommand{\bbZ}{\mathbb{Z}}`, which may be used to produce the &LaTeX; formula f : \bbZ^2 \to \bbZ. However, note that this only works in the PDF version of the file. Now edit PackageName/PackageInfo.g as follows. Delete any `PKGVERSIONDATA` chunk that may be there. One reason for converting your manual to use &AutoDoc; is to stop using entities such as `PACKAGENAMEVERSION`. Copy the `AutoDoc` record from AutoDoc/PackageInfo.g to the end of your file (just before the final `"));"`. Replace the `Copyright`, `Abstract` and `Acknowledgements` fields of the `TitlePage` record with the corresponding material from your manual.xml. (If you do not have an abstract, then delete the `Abstract` field, etc.) In the `entities` record enter any entities previously stored in your manual.xml. (Again, if you have none, you may safely delete this record.) To illustrate this option the &AutoDoc; file PackageInfo.g defines entities for the names of packages &io; and &PackageName;. If you are using a GitHub repository, as well as running "`git add`" on files makedoc.g, PackageInfo.g and doc/PackageName.bib, you should run "`git rm -f`" on files doc/manual.xml, and doc/title.xml. You should now be ready to run &GAP; and `Read("makedoc.g");` in your package root directory.

Scaffolds

Generating a title page

For most (if not all) &GAP; packages, the title page of the package manual lists information such as the release date, version, names and contact details of the authors, and so on.

All this data is also contained in your PackageInfo.g, and whenever you make a change to that file, there is a risk that you forget to update your manual to match. And even if you don't forget it, you of course have to spend some time to adjust the manual. &GAPDoc; can help to a degree with this via entities. Thus, you will sometimes see code like this in PackageInfo.g files:

    Version        := "1.2.3",
    Date           := "20/01/2015",
    ##  <#GAPDoc Label="PKGVERSIONDATA">
    ##  <!ENTITY VERSION "1.2.3">
    ##  <!ENTITY RELEASEDATE "20 January 2015">
    ##  <!ENTITY RELEASEYEAR "2015">
    ##  <#/GAPDoc>

However, it is still easy to forget both of these versions. And it doesn't solve the problem of updating package authors addresses. Neither of these is a big issue, of course, but there have been plenty examples in the past where people forget either of these two things, and it can be slightly embarrassing. It may even require you to make a new release just to fix the issue, which in our opinion is a sad waste of your valuable time.

So instead of worrying about manually synchronising these things, you can instruct &AutoDoc; to generate a title page for your manual based on the information in your PackageInfo.g. The following commands do just that (in addition to building your manual), by generating a file called doc/title.xml.

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( scaffold := rec( MainPage := false ) ) );

Note that this only outputs doc/title.xml but does not touch any other files of your documentation. In particular, you need to explicitly include doc/title.xml from your main XML file.

However, you can also tell &AutoDoc; to maintain the main XML file for you, in which case this is automatic. In fact, this is the default if you enable scaffolding; the above example command explicitly told &AutoDoc; not to generate a main page.

Generating the main XML file

The following generates a main XML file for your documentation in addition to the title page. The main XML file includes the title page by default, as well as any documentation generated from &AutoDoc; documentation comments.

    LoadPackage( "AutoDoc" );
    AutoDoc( rec( scaffold := true ) );

You can instruct &AutoDoc; to include additional XML files by giving it a list of filenames, as in the following example:

    LoadPackage( "AutoDoc" );
    AutoDoc(rec(
        scaffold := rec(
            includes := [ "somefile.xml", "anotherfile.xml" ]
        )
    ));

For more information, please consult the documentation of the function.

What data is used from PackageInfo.g?

&AutoDoc; can use data from PackageInfo.g in order to generate a title page. Specifically, the following components of the package info record are taken into account:

PackageName This is used to set the `<Title>` element of the title page. Subtitle This is used to set the `<Subtitle>` element of the title page. Version This is used to set the `<Version>` element of the title page, with the string Version prepended. Date This is used to set the `<Date>` element of the title page. Persons This is used to generate `<Author>` elements in the generated title page. PackageDoc This is a record (or a list of records) which is used to tell the &GAP; help system about the package manual. Currently &AutoDoc; extracts the value of the PackageDoc.BookName component and then passes that on to &GAPDoc; when creating the HTML, PDF and text versions of the manual. AutoDoc This record controls extra settings used by &AutoDoc; while generating the manual. In particular, PkgInfo.AutoDoc.TitlePage lets you add or override title-page elements coming from package metadata.

Typical fields you may set there include TitleComment, Abstract, Copyright, Acknowledgements and Colophon. For example, in PackageInfo.g:

    SetPackageInfo( rec(
      ...
      AutoDoc := rec(
        TitlePage := rec(
          Copyright := "(C) 2026 Jane Doe",
          Acknowledgements := "Funded by Example Grant 1234."
        )
      )
    ) );

This inserts `<Copyright>` and `<Acknowledgements>` blocks into the generated title.xml.

PkgInfo.AutoDoc.TitlePage has exactly the same meaning as scaffold.TitlePage in . The function documentation for scaffold.TitlePage points back to this subsection.

Entities from PackageInfo.g and scaffold options

Besides title-page fields, you can define custom entities in AutoDoc.entities inside PackageInfo.g. They are written to doc/_entities.xml, so they can be used both by generated main files and by hand-written main XML files.

In addition, &AutoDoc; predefines the entities VERSION, RELEASEYEAR and RELEASEDATE, derived from package metadata. This is useful if you keep a custom title page or custom chapters and still want release information to stay synchronized with PackageInfo.g.

You can specify scaffold-related settings in PackageInfo.g and in your makedoc.g call at the same time; both records are merged, and values from makedoc.g take precedence when both define the same key.

Worksheets

For stand-alone documents that are not tied to a package, use . Its documentation and examples are in Section of chapter .