Skip to content

docs: Clarify scan_dirs behavior #345

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 11, 2026
Merged

docs: Clarify scan_dirs behavior #345

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
23 changes: 14 additions & 9 deletions doc/Tutorials.autodoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,22 +275,27 @@ LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
```

As explained above, by default &AutoDoc; scans all <F>.g</F>, <F>.gd</F> and <F>.gi</F> files
it can find inside of your package root directory, and in the subdirectories <F>gap</F>,
<F>lib</F>, <F>examples</F> and <F>examples/doc</F> as well.
If you keep source files with documentation in other directories,
you can adjust the list of directories AutoDoc scans via the <C>scan_dirs</C> option.
The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory <F>package_sources</F>
of the package's root directory.
&AutoDoc; can scan directories for documentation input automatically.
In fact there are two separate scanning steps.
The option <C>autodoc.scan_dirs</C> controls where it looks for source comments beginning with
<C>#!</C> and for standalone <F>.autodoc</F> files.
By default, it scans the package root directory and the subdirectories <F>gap</F>,
<F>lib</F>, <F>examples</F> and <F>examples/doc</F>.
If you keep that kind of input in other directories, adjust <C>autodoc.scan_dirs</C>.
The following example instructs &AutoDoc; to only search in the subdirectory
<F>package_sources</F> of the package's root directory for those files.
```@listing
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
```
The separate option <C>gapdoc.scan_dirs</C> serves a different purpose:
it controls where &GAPDoc; comments are searched for.

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:
```@listing
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
```
Giving such a file does not prevent the standard <C>scan_dirs</C> from being scanned for
other files.
Expand Down
7 changes: 7 additions & 0 deletions gap/Magic.gd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,10 @@
#! A list of subdirectories of the package directory (given as relative paths)
#! which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
#! are then scanned for &AutoDoc; documentation comments.
#! This controls where &AutoDoc; looks for source comments beginning with <C>#!</C>
#! and for standalone <F>.autodoc</F> files.
#! It does not affect where &GAPDoc; looks for GAPDoc comments; that is controlled
#! separately by <A>gapdoc.scan_dirs</A>.
#! <Br/>
#! <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
#! </Item>
Expand Down Expand Up @@ -314,6 +318,9 @@
#! A list of subdirectories of the package directory (given as relative paths)
#! which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
#! are then scanned for &GAPDoc; documentation comments.
#! This controls only where &GAPDoc; comments are searched for.
#! It does not affect where &AutoDoc; looks for source comments beginning with <C>#!</C>
#! or for <F>.autodoc</F> files; use <A>autodoc.scan_dirs</A> for that.
#! <Br/>
#! <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
#! </Item>
Expand Down
7 changes: 7 additions & 0 deletions tst/manual.expected/_Chapter_Reference.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,10 @@
A list of subdirectories of the package directory (given as relative paths)
which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
are then scanned for &AutoDoc; documentation comments.
This controls where &AutoDoc; looks for source comments beginning with <C>#!</C>
and for standalone <F>.autodoc</F> files.
It does not affect where &GAPDoc; looks for GAPDoc comments; that is controlled
separately by <A>gapdoc.scan_dirs</A>.
<Br/>
<E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
</Item>
Expand Down Expand Up @@ -314,6 +318,9 @@
A list of subdirectories of the package directory (given as relative paths)
which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
are then scanned for &GAPDoc; documentation comments.
This controls only where &GAPDoc; comments are searched for.
It does not affect where &AutoDoc; looks for source comments beginning with <C>#!</C>
or for <F>.autodoc</F> files; use <A>autodoc.scan_dirs</A> for that.
<Br/>
<E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
</Item>
Expand Down
23 changes: 14 additions & 9 deletions tst/manual.expected/_Chapter_Tutorials.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -298,22 +298,27 @@ LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
]]></Listing>
<P/>
As explained above, by default &AutoDoc; scans all <F>.g</F>, <F>.gd</F> and <F>.gi</F> files
it can find inside of your package root directory, and in the subdirectories <F>gap</F>,
<F>lib</F>, <F>examples</F> and <F>examples/doc</F> as well.
If you keep source files with documentation in other directories,
you can adjust the list of directories AutoDoc scans via the <C>scan_dirs</C> option.
The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory <F>package_sources</F>
of the package's root directory.
&AutoDoc; can scan directories for documentation input automatically.
In fact there are two separate scanning steps.
The option <C>autodoc.scan_dirs</C> controls where it looks for source comments beginning with
<C>#!</C> and for standalone <F>.autodoc</F> files.
By default, it scans the package root directory and the subdirectories <F>gap</F>,
<F>lib</F>, <F>examples</F> and <F>examples/doc</F>.
If you keep that kind of input in other directories, adjust <C>autodoc.scan_dirs</C>.
The following example instructs &AutoDoc; to only search in the subdirectory
<F>package_sources</F> of the package's root directory for those files.
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
]]></Listing>
The separate option <C>gapdoc.scan_dirs</C> serves a different purpose:
it controls where &GAPDoc; comments are searched for.
<P/>
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:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
]]></Listing>
Giving such a file does not prevent the standard <C>scan_dirs</C> from being scanned for
other files.
Expand Down
Loading