chap1.txt

  
  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  GAPDoc, and 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   insider   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 (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  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 package 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 subfolder 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 a maketest.g file, which uses the
  examples in your manual to test your package. This can be achieved via
  
  
    LoadPackage( "AutoDoc" );
    AutoDoc( rec( maketest := true ) );
  
  
  Now the file maketest.g appears in your package directory, and
  
  
    gap maketest.g
  
  
  test the examples from your manual.
  
  
  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_source" ] ) ) );
  
  
  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 subfolder of your package. From this folder, 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.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 enabling
  scaffolding;  the  above  example  command  explicitly  told  AutoDoc not to
  generate a main page. More o
  
  
  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 extracted 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.
  
  
  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 folder of this file, the command
  
  
    AutoDocWorksheet( "worksheet.g" );
  
  
  will create a subfolder 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 maketest option from the AutoDoc 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