GAP (AutoDoc) - Chapter 1: Getting started using AutoDoc

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

[MathJax off]

1 Getting started using AutoDoc
1.1 Creating a package manual from scratch
1.2 Documenting code with AutoDoc
1.3 Using AutoDoc in an existing GAPDoc manual
1.3-1 Using AutoDoc on a complete GAPDoc manual
1.3-2 Setting different GAPDoc options
1.3-3 Checklist for converting an existing GAPDoc manual to use AutoDoc
1.4 Scaffolds
1.4-1 Generating a title page
1.4-2 Generating the main XML file
1.4-3 What data is used from `PackageInfo.g`?
1.5 AutoDoc worksheets

### 1 Getting started using AutoDoc

AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon the GAPDoc package (see https://www.gap-system.org/Packages/gapdoc.html). As such, it is not a replacement for GAPDoc, but rather complements it.

In this chapter we describe how to get started using AutoDoc for your package. First, we explain in Section 1.1 how to write a new package manual from scratch.

Then we show in Section 1.3 how you might benefit from AutoDoc even if you already have a complete manual written using GAPDoc.

In Section 1.4, we explain how you may use AutoDoc to generate a title page and the main XML file for your manual.

Finally, Section 1.5, explains what AutoDoc worksheets are and how to use them.

#### 1.1 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 `AutoDoc` (4.1-1) command like this, while running GAP from within your package's directory (the one containing the `PackageInfo.g` file):

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

This first reads the `PackageInfo.g` file from the current directory. It extracts information about package from it (such as its name and version, see Section 1.4-1). It then creates two XML files `doc/NAME_OF_YOUR_PACKAGE.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 GAPDoc: Distributing a Document into Several Files, as well as Section 1.3 of this manual on how to teach the `AutoDoc` (4.1-1) command to include this extra documentation. Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).

You will probably want to re-run the `AutoDoc` (4.1-1) 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 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, executed from within in the package directory:

    gap makedoc.g

#### 1.2 Documenting code with AutoDoc

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:

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

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

Suppose you have not been using GAPDoc before but instead used the process described in section 1.1 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. Just make sure to first edit the main XML file of your documentation, and insert the line

    <#Include SYSTEM "_AutoDocMainFile.xml">

in a suitable place. This means that you can mix AutoDoc documentation comment 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 the runs GAPDoc to produce HTML and PDF output, but does not touch your documentation XML files otherwise.

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

#### 1.3 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 off, with AutoDoc 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 only this purpose, e.g. io and orb.

##### 1.3-1 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 sessions started started in the root directory of your package:

    LoadPackage( "AutoDoc" );
    AutoDoc( );

In contrast, the RingsForHomalg currently uses essentially the following code in its `makedoc.g` file to achieve the same result

    LoadPackage( "GAPDoc" );
    SetGapDocLaTeXOptions( "utf8" );
    bib := ParseBibFiles( "doc/RingsForHomalg.bib" );
    WriteBibXMLextFile( "doc/RingsForHomalgBib.xml", bib );
    list := [
             "../gap/RingsForHomalg.gd",
             "../gap/RingsForHomalg.gi",
             "../gap/Singular.gi",
             "../gap/SingularBasic.gi",
             "../examples/RingConstructionsExternalGAP.g",
             "../examples/RingConstructionsSingular.g",
             "../examples/RingConstructionsMAGMA.g",
             "../examples/RingConstructionsMacaulay2.g",
             "../examples/RingConstructionsSage.g",
             "../examples/RingConstructionsMaple.g",
             ];
    MakeGAPDocDoc( "doc", "RingsForHomalg", list, "RingsForHomalg" );
    GAPDocManualLab( "RingsForHomalg" );

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 `Test` (Reference: Test) respectively `TestDirectory` (Reference: TestDirectory).

##### 1.3-2 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" ) ) );

As explained above, by default AutoDoc scans all `.g`, `.gd` and `.gi` files it can find inside of your package root directory, and in the subdirectories `gap`, `lib`, `examples` and `examples/doc` as well. If you keep source files with documentation in other directories, you can adjust the list of directories AutoDoc scans via the `scan_dirs` option. The following example illustrates this by instructing AutoDoc to only search in the subdirectory `package_sources` of the packages root directory.

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

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( gapdoc := rec( files := [ "path/to/some/hidden/file.gds" ] ) ) );

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 `AutoDoc` (4.1-1) 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 ) ) );

##### 1.3-3 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/PackageName.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\).

  - In the `entities` record enter any entities previously stored in `manual.xml`. (Again, if you have none, you may safely delete this record.) To illustrate this option the AutoDoc file `makedoc.g` defines entities for the names of packages io and PackageName.

- 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.) For other introductory components, such as `Colophon`, consult the file `gap/Magic.gd`.

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

#### 1.4 Scaffolds

##### 1.4-1 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.

##### 1.4-2 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 `AutoDoc` (4.1-1) function.

##### 1.4-3 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 is a record which can be used to control the scaffolding performed by AutoDoc, specifically to provide extra information for the title page. For example, you can set `AutoDoc.TitlePage.Copyright` to a string which will then be inserted on the generated title page. Using this method you can customize the following title page elements: `TitleComment`, `Abstract`, `Copyright`, `Acknowledgements` and `Colophon`.

  Note that `AutoDoc.TitlePage` behaves exactly the same as the `scaffold.TitlePage` parameter of the `AutoDoc` (4.1-1) function.

#### 1.5 AutoDoc worksheets

AutoDoc worksheets can be used to create HTML and PDF documents using AutoDoc syntax and possibly including GAP examples and implementations without having them associated to a package. A file for a worksheet could look like this:

    #! @Title My first worksheet
    #! @Author Charlie Brown

    #! @Chapter Some groups

    #! @BeginExample
    S3 := SymmetricGroup( 3 );;
    S4 := SymmetricGroup( 4 );;
    #! @EndExample

Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as `worksheet.g`. Then, when GAP is started in the directory of this file, the command

    AutoDocWorksheet( "worksheet.g" );

will create a subdirectory called `doc` of the current directory in which it will create the documentation. There are several options to configure the output of the worksheet command, which are identical to the options of the `AutoDoc` (4.1-1) command. It is even possible to test the examples in the worksheet using the `extract_examples` option of the `AutoDoc` (4.1-1) command.

Since the worksheets do not have a `PackageInfo.g` to extract information, all possible tags that GAPDoc supports for the title page can be set into the document. A fully typed title page can look like this:

    #! @Title My first worksheet
    #! @Subtitle Some small examples
    #! @Author Charlie Brown

    #! @Version 0.1
    #! @TitleComment Some worksheet
    #! @Date 01/01/2016
    #! @Address TU Kaiserslautern
    #! @Abstract
    #!  A worksheet showing some small examples about groups.
    #! @Copyright 2016 Charlie Brown
    #! @Acknowledgements Woodstock
    #! @Colophon Some colophon

    #! @Chapter Some groups

    #! @BeginExample
    S3 := SymmetricGroup( 3 );;
    S4 := SymmetricGroup( 4 );;
    #! @EndExample

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

generated by GAPDoc2HTML