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

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

[MathJax on]

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.4 Automatic regeneration of the manual
1.5 What is taken from `PackageInfo.g`

### 1 Getting started using AutoDoc

AutoDoc is a GAP package which is meant to aide GAP package authors in creating and maintaing the documentation of their packages. In this capacity it builds upon GAPDoc (and hence is not a replacement for it, but rather a complement). In this chapter we describe how you can get started using AutoDoc for your package. To this end, we will assume from now on that your package is called SomePackage.

#### 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 manual using the `AutoDoc` (4.1-1) command like this:

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

This creates two XML files `doc/SomePackage.xml` and `doc/title.xml` insider the package directory and then 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 the following (or a variation of it) 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 (in either case, see Section 1.3 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 may also wish to consult Section 1.4 for hints on automatically re-generating your package manual when necessary.

#### 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("SomePackage" : 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("SomePackage" : autodoc := true );

#### 1.3 Using AutoDoc in an existing GAPDoc manual

TODO: Explain that it might still be interesting to switch to using scaffolding?

TODO: Demonstrate how to add / mix your own XML files, AutoDoc generated XML files, and GAPDoc stuff...

#### 1.4 Automatic regeneration of the manual

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. Then you can regenerate the manual from the command line with the following simple command (assuming you are in the package directory):

    gap makedoc.g

#### 1.5 What is taken from `PackageInfo.g`

AutoDoc can extract data from `PackageInfo.g` in order to generate a title page. Specifically, the following components of the package info record are looked at:

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.

Subtitle

  This is used to set the `<Subtitle>` element of the title page (the `<Title>` is set to the package name).

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.

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

generated by GAPDoc2HTML