Skip to content

Switch makedoc.g to using AutoDoc #53

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
olexandr-konovalov merged 1 commit into from
Aug 10, 2026
Merged

Switch makedoc.g to using AutoDoc #53

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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,4 @@ doc/*.six
doc/*.tex
doc/*.toc
doc/*.txt
doc/_*.xml
32 changes: 25 additions & 7 deletions PackageInfo.g
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,6 @@ Subtitle := "Symbolic Computation Software Composability Protocol in GAP",
Version := "2.4.4",
Date := "27/08/2025", # dd/mm/yyyy format
License := "GPL-2.0-or-later",
## <#GAPDoc Label="PKGVERSIONDATA">
## <!ENTITY VERSION "2.4.4">
## <!ENTITY RELEASEDATE "27 August 2025">
## <!ENTITY RELEASEYEAR "2025">
## <#/GAPDoc>

SourceRepository := rec(
Type := "git",
Expand Down Expand Up @@ -101,6 +96,29 @@ Dependencies := rec(
AvailabilityTest := ReturnTrue,
TestFile := "tst/offline.tst",

Keywords := [ "SCSCP", "software composability", "interface",
"parallel computing", "OpenMath" ]
Keywords := [ "SCSCP", "software composability", "interface",
"parallel computing", "OpenMath" ],

AutoDoc := rec(
entities := rec(
IO := "<Package>IO</Package>",
OpenMath := "<Package>OpenMath</Package>",
scscp1 := "<Package>scscp1</Package>",
scscp2 := "<Package>scscp2</Package>",
ANUPQ := "<Package>ANUPQ</Package>",
EdenTV := "<Package>EdenTV</Package>",
VERSION := ~.Version,
RELEASEYEAR := ~.Date{[7..10]},
RELEASEDATE := function(date)
local day, month, year, allMonths;
day := Int(date{[1,2]});
month := Int(date{[4,5]});
year := Int(date{[7..10]});
allMonths := [ "January", "February", "March", "April", "May", "June", "July",
"August", "September", "October", "November", "December"];
return Concatenation(String(day)," ", allMonths[month], " ", String(year));
end(~.Date),
),
),

));
13 changes: 3 additions & 10 deletions doc/manual.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,9 @@

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE Book SYSTEM "gapdoc.dtd"
[ <!ENTITY IO "<Package>IO</Package>">
<!ENTITY OpenMath "<Package>OpenMath</Package>">
<!ENTITY scscp1 "<Package>scscp1</Package>">
<!ENTITY scscp2 "<Package>scscp2</Package>">
<!ENTITY ANUPQ "<Package>ANUPQ</Package>">
<!ENTITY EdenTV "<Package>EdenTV</Package>">
<!ENTITY SCSCP "<Package>SCSCP</Package>">
<#Include Label="PKGVERSIONDATA">
] >
<!DOCTYPE Book SYSTEM "gapdoc.dtd" [
<#Include SYSTEM "_entities.xml">
] >

<Book Name="scscp">

Expand Down
131 changes: 26 additions & 105 deletions makedoc.g
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,105 +1,26 @@
###########################################################################
##
#W makedoc.g The SCSCP package Olexandr Konovalov
#W Steve Linton
##
###########################################################################

ExtractMyManualExamples:=function( pkgname, main, files )
local path, tst, i, s, basename, name, output, ch, a, location, pos, comment;
path:=Directory(
Concatenation(PackageInfo(pkgname)[1].InstallationPath, "/doc") );
Print("Extracting manual examples for ", pkgname, " package ...\n" );
tst:=ExtractExamples( path, main, files, "Chapter" );
Print(Length(tst), " chapters detected\n");
for i in [ 1 .. Length(tst) ] do
Print( "Chapter ", i, " : \c" );
if Length( tst[i] ) > 0 then
s := String(i);
if Length(s)=1 then
# works for <100 chapters
s:=Concatenation("0",s);
fi;
basename:=Concatenation( LowercaseString(pkgname), s, ".tst" );
name := Filename(
Directory(
Concatenation( PackageInfo(pkgname)[1].InstallationPath,
"/tst" ) ), basename );
output := OutputTextFile( name, false ); # to empty the file first
SetPrintFormattingStatus( output, false ); # to avoid line breaks
ch := tst[i];
AppendTo(output, "# ", pkgname, ", chapter ",i,"\n");
AppendTo(output, "#\n",
"# DO NOT EDIT THIS FILE - EDIT EXAMPLES IN THE SOURCE INSTEAD!\n",
"#\n",
"# This file has been autogenerated with GAP. It contains examples\n",
"# extracted from the documentation. Each example is preceded by the\n",
"# comment which points to the location of its source.\n",
"#\n");
AppendTo(output, "gap> START_TEST( \"", basename, "\");\n\n");
for a in ch do
location := a[2][1];
pos := PositionSublist(location,Concatenation(pkgname,"/"));
if pos <> fail then
comment := location{[ pos+Length(pkgname)+1 .. Length(location) ]};
else
pos := PositionSublist(location,".//");
comment := location{[ pos+3 .. Length(location) ]};
fi;
AppendTo(output, "# ", comment, ":", a[2][2], "-", a[2][3], "\n", StripBeginEnd(a[1], "\n"), "\n\n");
od;
AppendTo(output, "#\ngap> STOP_TEST(\"", basename, "\", 1 );\n");
Print("extracted ", Length(ch), " examples \n");
else
Print("no examples \n" );
fi;
od;
end;

###########################################################################

SCSCPMANUALFILES:=[
"../PackageInfo.g",
"../lib/connect.gd",
"../lib/openmath.gd",
"../lib/process.gd",
"../lib/remote.gd",
"../lib/scscp.gd",
"../lib/utils.g",
"../lib/xstream.gd",
"../par/parlist.g",
"../tracing/tracing.g",
];

###########################################################################

MakeGAPDocDoc( "doc", # path to the directory containing the main file
"manual", # the name of the main file (without extension)
# list of (probably source code) files relative
# to path which contain pieces of documentation
# which must be included in the document
SCSCPMANUALFILES,
"scscp", # the name of the book used by GAP's online help
"../../..",# optional: relative path to the main GAP root
# directory to produce HTML files with relative
# paths to external books.
"MathJax" # optional: use "MathJax", "Tth" and/or "MathML"
# to produce additional variants of HTML files
);;

# Copy the *.css and *.js files from the styles directory of the GAPDoc
# package into the directory containing the package manual.
CopyHTMLStyleFiles( "doc" );

# Create the manual.lab file which is needed if the main manuals or another
# package is referring to your package
GAPDocManualLab( "scscp" );;

ExtractMyManualExamples( "scscp", "manual.xml", SCSCPMANUALFILES );

QUIT;

###########################################################################
##
#E
##
#
# This file is a script which compiles the package manual.
#
if fail = LoadPackage("AutoDoc", "2022.07.10") then
Error("AutoDoc version 2022.07.10 or newer is required.");
fi;

AutoDoc(rec(
autodoc := true,
extract_examples := true,
gapdoc := rec(
main := "manual.xml",
files := [
"lib/connect.gd",
"lib/openmath.gd",
"lib/process.gd",
"lib/remote.gd",
"lib/scscp.gd",
"lib/utils.g",
"lib/xstream.gd",
"par/parlist.g",
"tracing/tracing.g",
],
),
scaffold := rec( MainPage := false, TitlePage := false ),
));
140 changes: 140 additions & 0 deletions tst/scscp01.tst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# SCSCP, chapter 4
#
# DO NOT EDIT THIS FILE - EDIT EXAMPLES IN THE SOURCE INSTEAD!
#
# This file has been generated by AutoDoc. It contains examples extracted from
# the package documentation. Each example is preceded by a comment which gives
# the name of a GAPDoc XML file and a line range from which the example were
# taken. Note that the XML file in turn may have been generated by AutoDoc
# from some other input.
#
gap> START_TEST("scscp01.tst");

# doc/../lib/scscp.gd:492-500

gap> s := InputOutputTCPStream("localhost",26133);
< input/output TCP stream to localhost:26133 >
gap> StartSCSCPsession(s);
"localhost:26133:5541"
gap> CloseStream( s );


# doc/../lib/openmath.gd:120-159

gap> t:="";; stream:=OutputTextString(t,true);;
gap> OMPutProcedureCall( stream, "WS_Factorial", rec( object:= [ 5 ],
> attributes:=[ [ "call_id", "user007" ],
> ["option_runtime",1000],
> ["option_min_memory",1024],
> ["option_max_memory",2048],
> ["option_debuglevel",1],
> ["option_return_object"] ] ) );;
gap> Print(t);
<?scscp start ?>
<OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
<OMATTR>
<OMATP>
<OMS cd="scscp1" name="call_id"/>
<OMSTR>user007</OMSTR>
<OMS cd="scscp1" name="option_runtime"/>
<OMI>1000</OMI>
<OMS cd="scscp1" name="option_min_memory"/>
<OMI>1024</OMI>
<OMS cd="scscp1" name="option_max_memory"/>
<OMI>2048</OMI>
<OMS cd="scscp1" name="option_debuglevel"/>
<OMI>1</OMI>
<OMS cd="scscp1" name="option_return_object"/>
<OMSTR></OMSTR>
</OMATP>
<OMA>
<OMS cd="scscp1" name="procedure_call"/>
<OMA>
<OMS cd="scscp_transient_1" name="WS_Factorial"/>
<OMI>5</OMI>
</OMA>
</OMA>
</OMATTR>
</OMOBJ>
<?scscp end ?>


# doc/../lib/openmath.gd:44-77

gap> InstallSCSCPprocedure("WS_Factorial", Factorial );
gap> InstallSCSCPprocedure("GroupIdentificationService", IdGroup );
gap> InstallSCSCPprocedure("GroupByIdNumber", SmallGroup );
gap> InstallSCSCPprocedure( "Length", Length, 1, 1 );
gap> test:=Filename( Directory( Concatenation(
> GAPInfo.PackagesInfo.("scscp")[1].InstallationPath,"/tst/" ) ),
> "omdemo.om" );;
gap> stream:=InputTextFile(test);;
gap> OMGetObjectWithAttributes(stream);
rec(
attributes := [ [ "option_return_object", "" ], [ "call_id", "5rc6rtG62" ] ]
, object := 6 )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [ ], object := 1 )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [ ], object := 120 )
gap> OMGetObjectWithAttributes(stream);
rec(
attributes := [ [ "call_id", "alexk_9053" ], [ "option_runtime", 300000 ],
[ "option_min_memory", 40964 ], [ "option_max_memory", 134217728 ],
[ "option_debuglevel", 2 ], [ "option_return_object", "" ] ],
object := [ 24, 12 ] )
gap> OMGetObjectWithAttributes(stream);
rec(
attributes := [ [ "call_id", "alexk_9053" ], [ "option_return_cookie", "" ]
], object := <pc group of size 24 with 4 generators> )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [ [ "call_id", "alexk_9053" ], [ "info_runtime", 1234 ],
[ "info_memory", 134217728 ] ], object := [ 24, 12 ] )
gap> CloseStream( stream );


# doc/../lib/openmath.gd:184-207

gap> t:="";; stream:=OutputTextString(t,true);;
gap> OMPutProcedureCompleted( stream,
> rec(object:=120,
> attributes:=[ [ "call_id", "user007" ] ] ) );
true
gap> Print(t);
<?scscp start ?>
<OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
<OMATTR>
<OMATP>
<OMS cd="scscp1" name="call_id"/>
<OMSTR>user007</OMSTR>
</OMATP>
<OMA>
<OMS cd="scscp1" name="procedure_completed"/>
<OMI>120</OMI>
</OMA>
</OMATTR>
</OMOBJ>
<?scscp end ?>


# doc/openmath.xml:50-68
gap> stream:=InputOutputTCPStream( "localhost", 26133 );
< input/output TCP stream to localhost:26133 >
gap> sid := StartSCSCPsession( stream );
"localhost:26133:5541"
gap> res:=[];
[ ]
gap> for i in [1..10] do
> OMPutProcedureCall( stream, "WS_Factorial",
> rec( object := [ i ],
> attributes := [ [ "call_id",
> Concatenation( sid, ":", RandomString(8) ) ] ] ) );
> SCSCPwait( stream );
> res[i]:=OMGetObjectWithAttributes( stream ).object;
> od;
gap> CloseStream(stream);
gap> res;
[ 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800 ]

#
gap> STOP_TEST("scscp01.tst", 1);
Loading