homalg-project/AutoDoc — pull request #16 by fingolfin (2013-08-01 02:28:27+00:00)
Title: Magic function to (re)generate documentation via GAPDoc and AutoDoc

DO NOT MERGE THIS IN THE CURRENT FORM!!!!

This pull request is merely here to give convenient access to this prototype, and to allow discussing it. There are various FIXMEs and TODOs in the code and lots of issues with the code. These need to be addressed before merging this.

That said, let me explain what this code does: It adds a new function `GenerateDocumentation` which basically combines the functionality of makedoc.g, createautodoc.g and ListOfDocFiles.g. This function takes two to three parameters: The name of the package whose documentation we want to generate; a boolean flag which indicates whether to scaffold XML files (this is passed as `create_full_docu` to `CreateAutomaticDocumentation`), and an (optional) options record. This

An example invocation for the AutoDocTestPackage looks like this (and can be used to fully replace makedoc.g, createautodoc.g and ListOfDocFiles.g for that package):
```
LoadPackage("AutoDoc");

GenerateDocumentation(
"AutoDocTestPackage",
true,
rec(
autodoc_output := "gap/documentation_file.d",
gapdoc_scan_dirs := [ "../gap" ],
section_intros :=
[
[ "Intro", "This is a test docu" ],
[ "With_chapter_info", "This is a user set chapter" ],
[ "With_chapter_info", "Category_section", [ "This section", "is for categories" ] ]
],
)
);
```

However, it is also possible to customize many things:
```
LoadPackage("AutoDoc");

GenerateDocumentation(
"AutoDocTestPackage",
true,
rec(
dir := "Documentation", # default: "doc"
autodoc_output := "gap/documentation_file.d",
gapdoc_files := [
"../gap/documentation_file.d", # FIXME: ought to be automatically added to list, but this is a buggy
"../gap/Declarations.gd",
]
section_intros :=
[
[ "Intro", "This is a test docu" ],
[ "With_chapter_info", "This is a user set chapter" ],
[ "With_chapter_info", "Category_section", [ "This section", "is for categories" ] ]
],
entities := [ "WeLoveHomalg" ],
)
);
```

Now, this is useful even for packages that do not (yet) use AutoDoc, simply because of the scaffolding capaability (inherited from CreateAutomaticDocumentation): With it, ensuring your main GAPDoc XML file and your PackageInfo.g stay in sync becomes a breeze.

Indeed, this makes GenerateDocumentation() a perfect way to add documentation to a package that does not yet have any: Simply invoke GenerateDocumentation("MyPackage", true") and you are done.

Some things that need to be done:
- [ ] to make that last bit really work, create the "doc/" dir (resp. opt.dir) if it is missing
- [ ] find a better name than `GenerateDocumentation`
- [ ] fix adding opt.autodoc_output to opt.gapdoc_files (this is problematic because AutoDoc and GAPDoc treat relative paths differently)
- [ ] add documentation
- [ ] make sure this is usable even for packages which do not to use AutoDoc otherwise
- [ ] related to the above: do not always create a `VERSION` file. At the very least, make it possible to turn that off
- [ ] test it more, and possible convert more packages to using it
- [ ] consider adding more customization options (but don't overdo it), esp. to the scaffolding. One thing that comes to mind: a flag which indicates whether the author's address should be formatted in multiple lines (as it is now), or in a single line (as the AutoDoc manual currently uses)