Skip to content

docs: clarify standalone autodoc files #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fingolfin merged 1 commit into from
Mar 8, 2026
Merged

docs: clarify standalone autodoc files #331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 93 additions & 2 deletions doc/Comments.autodoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -542,8 +542,99 @@ since worksheets do not have a <F>PackageInfo.g</F> file from which this informa
Files that have the suffix <C>.autodoc</C> and are listed in the
<C>autodoc.files</C> option of <Ref Func="AutoDoc"/>, resp. are contained in
one of the directories listed in <C>autodoc.scan_dirs</C>, are treated as
&AutoDoc; plain text files. These work exactly like &AutoDoc; comments, except
that lines do not need to (and in fact, should not) start with <C>#!</C>.
standalone &AutoDoc; input files. They are meant for manual text that does not
belong next to a single declaration: chapters, sections, tutorials, worked
examples, index entries, chunks, title-page metadata, and similar prose-heavy
material.

Conceptually, a <F>.autodoc</F> file uses the same parser as &AutoDoc;
comments, but without the comment marker. In a <F>.autodoc</F> file, lines do
not need to start with <C>#!</C> and in fact usually should not. This makes
<F>.autodoc</F> files one convenient way to replace hand-written XML chapters
when you prefer &AutoDoc;'s command syntax and Markdown-like text features.
However, it is not the only supported style: chapter and section commands inside
source comments remain fully supported, and &AutoDoc; itself still uses that
style in files such as <F>gap/Magic.gd</F>. For the surrounding workflow, see
Chapter <Ref Chap="Chapter_Tutorials"/>.

The most important difference from declaration comments is that a plain text
file does <E>not</E> document a declaration by adjacency. There is no following
<C>Declare...</C> or <C>InstallMethod</C> statement for &AutoDoc; to inspect.
So commands whose meaning depends on such a declaration only make sense in
source comments immediately before that declaration.

In practice, this gives the following rule of thumb.

<List>
<Item>
Use source comments beginning with <C>#!</C> to document declarations.
This is the mode for <C>@Description</C>, <C>@Returns</C>,
<C>@Arguments</C>, <C>@Label</C>, <C>@Group</C>, and <C>@ChapterInfo</C>.
</Item>
<Item>
Use either <F>.autodoc</F> files or source comments for standalone manual
structure and prose. Commands such as <C>@Chapter</C>, <C>@Section</C>,
<C>@Subsection</C>, grouping commands, examples and logs, chunks and code
insertion, <C>@Index</C>, title-page commands, Markdown-style headings,
fenced code blocks, and ordinary &GAPDoc; XML markup work in both styles.
</Item>
</List>

As a concrete example, the following file can serve as a complete chapter
written in <F>.autodoc</F> format.

```@listing
@Chapter Test
@Section First Section
@Subsection First Subsection

This text belongs directly to the manual chapter.
It can use XML tags such as <A>arg</A> or <C>&lt;Ref ...&gt;</C>.

@BeginExampleSession
gap> S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
gap> Size(S5);
120
@EndExampleSession

@Index "Worksheet Autoplain" Plain worksheet index entry with `true`
```

This is essentially the style used in the worksheet fixture
<F>tst/worksheets/autoplain.sheet/plain.autodoc</F>.

The same structural commands can also be used inside source comments, for
example:

```@listing
#! @Chapter Reference
#! @Section The AutoDoc() function
#! Some introductory text for this section.
```

This source-comment style is still fully supported and is used in
<F>gap/Magic.gd</F>.

The mixed-workflow case is equally common. Suppose an existing manual still has
a hand-written main XML file and perhaps some hand-written XML chapters. Then
you can keep those files, include <F>_AutoDocMainFile.xml</F> from the main XML
file as described in Chapter <Ref Chap="Chapter_Tutorials"/>, and add one or
more <F>.autodoc</F> files via <C>autodoc.files</C> or <C>autodoc.scan_dirs</C>.
Those files can provide tutorial chapters or appendices, while declaration
documentation continues to live in source comments and older XML chapters remain
unchanged.

One caveat is worth keeping in mind. If you want a standalone
<F>.autodoc</F> file to pause and resume around declaration documentation that
is written in source comments, the current workaround is to use chunks. That
interleaving workflow is currently limited; see issue <C>#60</C> in the
AutoDoc issue tracker.

So, while <F>.autodoc</F> files and source comments share most of the same text
syntax, they can be combined freely. The main distinction is simply that
declaration-bound commands attach metadata to a following declaration, while
standalone manual text can live wherever you find it most convenient.

@Section Grouping
@SectionLabel Groups
Expand Down
6 changes: 5 additions & 1 deletion doc/Overview.autodoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ you can adopt only the parts that help you today, and add more over time.
<C>extract_examples := true</C>.
- Document declarations directly in source files via &AutoDoc;
comments beginning with <C>#!</C>.
- Organize chapter and section text either in source comments or in
standalone <F>.autodoc</F> files.
- Combine &AutoDoc; comments, classic &GAPDoc; source comments,
and hand-written XML chapters in one manual.

Expand All @@ -35,6 +37,8 @@ Typical adoption paths include:
- Keep your existing title page but use generated entities such as
<C>&amp;VERSION;</C>, <C>&amp;RELEASEYEAR;</C>, and <C>&amp;RELEASEDATE;</C>.
- Add &AutoDoc; comments only for new code, and leave old documentation as-is.
- Keep existing XML chapters, or gradually add source comments and
<F>.autodoc</F> files where they fit your preferred workflow.
- Later, gradually move chapters or source documentation to your preferred style.

This flexibility is central: &AutoDoc; should make your current setup better,
Expand All @@ -45,4 +49,4 @@ without forcing a full rewrite first.

For practical setup and migration workflows, continue with chapter
<Ref Chap="Chapter_Tutorials"/>. For the command reference of documentation comments,
see chapter <Ref Chap="Chapter_Comments"/>.
including standalone <F>.autodoc</F> files, see chapter <Ref Chap="Chapter_Comments"/>.
27 changes: 25 additions & 2 deletions doc/Tutorials.autodoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,14 @@ Section <Ref Sect="Subsection_Tut:IntegrateExisting:EverythingThere"/>.
@Section Documenting code with &AutoDoc;
@SectionLabel Tut:AdvancedAutoDoc

&AutoDoc; supports several equally supported ways to organize your manual text.
You can put chapter and section material directly into <C>#!</C> comments inside
<F>.g</F>, <F>.gd</F>, or <F>.gi</F> files, you can put it into standalone
<F>.autodoc</F> 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
<Ref Chap="Chapter_Comments"/>, especially Section <Ref Sect="Section_PlainText"/>.

To get one of your global functions, operations, attributes
etc. to appear in the package manual, simply insert an &AutoDoc; comment
of the form <C>#!</C> directly in front of it. For example:
Expand Down Expand Up @@ -127,6 +135,21 @@ interpreted as &AutoDoc; commands). So, for instance, tags like
<C>&lt;Ref&gt;</C>, <C>&lt;A&gt;</C>, <C>&lt;K&gt;</C>, <C>&lt;List&gt;</C>, etc. can be written
directly in <C>#!</C> comment text.

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

One caveat applies if you decide to keep prose in a standalone
<F>.autodoc</F> 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 <C>#60</C> in the
AutoDoc issue tracker.

For a thorough description of what you can do with &AutoDoc;
documentation comments, please refer to chapter <Ref Chap="Chapter_Comments"/>.

Expand Down Expand Up @@ -168,13 +191,13 @@ AutoDoc( rec( scaffold := 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
documentation comments and standalone <F>.autodoc</F> files. Just make sure to first edit the main XML
file of your documentation, and insert the line
```@listing
&lt;#Include SYSTEM "_AutoDocMainFile.xml">
```
in a suitable place. This means that you can mix &AutoDoc; documentation
comments freely with your existing documentation; you can even still make
comments and <F>.autodoc</F> 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
Expand Down
95 changes: 93 additions & 2 deletions tst/manual.expected/_Chapter_Comments.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -646,8 +646,99 @@ since worksheets do not have a <F>PackageInfo.g</F> file from which this informa
Files that have the suffix <C>.autodoc</C> and are listed in the
<C>autodoc.files</C> option of <Ref Func="AutoDoc"/>, resp. are contained in
one of the directories listed in <C>autodoc.scan_dirs</C>, are treated as
&AutoDoc; plain text files. These work exactly like &AutoDoc; comments, except
that lines do not need to (and in fact, should not) start with <C>#!</C>.
standalone &AutoDoc; input files. They are meant for manual text that does not
belong next to a single declaration: chapters, sections, tutorials, worked
examples, index entries, chunks, title-page metadata, and similar prose-heavy
material.
<P/>
Conceptually, a <F>.autodoc</F> file uses the same parser as &AutoDoc;
comments, but without the comment marker. In a <F>.autodoc</F> file, lines do
not need to start with <C>#!</C> and in fact usually should not. This makes
<F>.autodoc</F> files one convenient way to replace hand-written XML chapters
when you prefer &AutoDoc;'s command syntax and Markdown-like text features.
However, it is not the only supported style: chapter and section commands inside
source comments remain fully supported, and &AutoDoc; itself still uses that
style in files such as <F>gap/Magic.gd</F>. For the surrounding workflow, see
Chapter <Ref Chap="Chapter_Tutorials"/>.
<P/>
The most important difference from declaration comments is that a plain text
file does <E>not</E> document a declaration by adjacency. There is no following
<C>Declare...</C> or <C>InstallMethod</C> statement for &AutoDoc; to inspect.
So commands whose meaning depends on such a declaration only make sense in
source comments immediately before that declaration.
<P/>
In practice, this gives the following rule of thumb.
<P/>
<List>
<Item>
Use source comments beginning with <C>#!</C> to document declarations.
This is the mode for <C>@Description</C>, <C>@Returns</C>,
<C>@Arguments</C>, <C>@Label</C>, <C>@Group</C>, and <C>@ChapterInfo</C>.
</Item>
<Item>
Use either <F>.autodoc</F> files or source comments for standalone manual
structure and prose. Commands such as <C>@Chapter</C>, <C>@Section</C>,
<C>@Subsection</C>, grouping commands, examples and logs, chunks and code
insertion, <C>@Index</C>, title-page commands, Markdown-style headings,
fenced code blocks, and ordinary &GAPDoc; XML markup work in both styles.
</Item>
</List>
<P/>
As a concrete example, the following file can serve as a complete chapter
written in <F>.autodoc</F> format.
<P/>
<Listing><![CDATA[
@Chapter Test
@Section First Section
@Subsection First Subsection

This text belongs directly to the manual chapter.
It can use XML tags such as <A>arg</A> or <C>&lt;Ref ...&gt;</C>.

@BeginExampleSession
gap> S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
gap> Size(S5);
120
@EndExampleSession

@Index "Worksheet Autoplain" Plain worksheet index entry with `true`
]]></Listing>
<P/>
This is essentially the style used in the worksheet fixture
<F>tst/worksheets/autoplain.sheet/plain.autodoc</F>.
<P/>
The same structural commands can also be used inside source comments, for
example:
<P/>
<Listing><![CDATA[
#! @Chapter Reference
#! @Section The AutoDoc() function
#! Some introductory text for this section.
]]></Listing>
<P/>
This source-comment style is still fully supported and is used in
<F>gap/Magic.gd</F>.
<P/>
The mixed-workflow case is equally common. Suppose an existing manual still has
a hand-written main XML file and perhaps some hand-written XML chapters. Then
you can keep those files, include <F>_AutoDocMainFile.xml</F> from the main XML
file as described in Chapter <Ref Chap="Chapter_Tutorials"/>, and add one or
more <F>.autodoc</F> files via <C>autodoc.files</C> or <C>autodoc.scan_dirs</C>.
Those files can provide tutorial chapters or appendices, while declaration
documentation continues to live in source comments and older XML chapters remain
unchanged.
<P/>
One caveat is worth keeping in mind. If you want a standalone
<F>.autodoc</F> file to pause and resume around declaration documentation that
is written in source comments, the current workaround is to use chunks. That
interleaving workflow is currently limited; see issue <C>#60</C> in the
AutoDoc issue tracker.
<P/>
So, while <F>.autodoc</F> files and source comments share most of the same text
syntax, they can be combined freely. The main distinction is simply that
declaration-bound commands attach metadata to a following declaration, while
standalone manual text can live wherever you find it most convenient.
<P/>
</Section>

Expand Down
10 changes: 9 additions & 1 deletion tst/manual.expected/_Chapter_Overview.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Document declarations directly in source files via &AutoDoc;
comments beginning with <C>#!</C>.
</Item>
<Item>
Organize chapter and section text either in source comments or in
standalone <F>.autodoc</F> files.
</Item>
<Item>
Combine &AutoDoc; comments, classic &GAPDoc; source comments,
and hand-written XML chapters in one manual.
</Item>
Expand Down Expand Up @@ -67,6 +71,10 @@ Keep your existing title page but use generated entities such as
Add &AutoDoc; comments only for new code, and leave old documentation as-is.
</Item>
<Item>
Keep existing XML chapters, or gradually add source comments and
<F>.autodoc</F> files where they fit your preferred workflow.
</Item>
<Item>
Later, gradually move chapters or source documentation to your preferred style.
</Item>
</List>
Expand All @@ -83,7 +91,7 @@ without forcing a full rewrite first.
<P/>
For practical setup and migration workflows, continue with chapter
<Ref Chap="Chapter_Tutorials"/>. For the command reference of documentation comments,
see chapter <Ref Chap="Chapter_Comments"/>.
including standalone <F>.autodoc</F> files, see chapter <Ref Chap="Chapter_Comments"/>.
</Section>


Expand Down
27 changes: 25 additions & 2 deletions tst/manual.expected/_Chapter_Tutorials.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,14 @@ Section <Ref Sect="Subsection_Tut:IntegrateExisting:EverythingThere"/>.
<Section Label="Section_Tut:AdvancedAutoDoc">
<Heading>Documenting code with &AutoDoc;</Heading>

<P/>
&AutoDoc; supports several equally supported ways to organize your manual text.
You can put chapter and section material directly into <C>#!</C> comments inside
<F>.g</F>, <F>.gd</F>, or <F>.gi</F> files, you can put it into standalone
<F>.autodoc</F> 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
<Ref Chap="Chapter_Comments"/>, especially Section <Ref Sect="Section_PlainText"/>.
<P/>
To get one of your global functions, operations, attributes
etc. to appear in the package manual, simply insert an &AutoDoc; comment
Expand Down Expand Up @@ -147,6 +155,21 @@ interpreted as &AutoDoc; commands). So, for instance, tags like
<C>&lt;Ref&gt;</C>, <C>&lt;A&gt;</C>, <C>&lt;K&gt;</C>, <C>&lt;List&gt;</C>, etc. can be written
directly in <C>#!</C> comment text.
<P/>
For chapter text, tutorial material, worked examples, and similar prose, some
authors prefer to keep the material next to their code using
<C>#! @Chapter</C>, <C>#! @Section</C>, and related commands, while others prefer
standalone <F>.autodoc</F> files. In an <F>.autodoc</F> file you write the same
commands without the <C>#!</C> prefix, and you list the file in
<C>autodoc.files</C> or place it in a directory scanned via
<C>autodoc.scan_dirs</C>. AutoDoc itself still uses the source-comment style in
places, for example in <F>gap/Magic.gd</F>.
<P/>
One caveat applies if you decide to keep prose in a standalone
<F>.autodoc</F> 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 <C>#60</C> in the
AutoDoc issue tracker.
<P/>
For a thorough description of what you can do with &AutoDoc;
documentation comments, please refer to chapter <Ref Chap="Chapter_Comments"/>.
<P/>
Expand Down Expand Up @@ -187,13 +210,13 @@ AutoDoc( rec( scaffold := true,
<P/>
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
documentation comments and standalone <F>.autodoc</F> files. Just make sure to first edit the main XML
file of your documentation, and insert the line
<Listing><![CDATA[
&lt;#Include SYSTEM "_AutoDocMainFile.xml">
]]></Listing>
in a suitable place. This means that you can mix &AutoDoc; documentation
comments freely with your existing documentation; you can even still make
comments and <F>.autodoc</F> files freely with your existing documentation; you can even still make
use of any existing &GAPDoc; documentation comments in your code.
<P/>
The following command should be useful for you in this case; it
Expand Down