Skip to content

Commit 24d62d4

Browse files
mohamed-barakatmohamed-barakat
authored
Merge pull request #40 from mohamed-barakat/Documentation
Improved documentation
2 parents 7a0c2b1 + 38b0b57 commit 24d62d4

File tree

4 files changed

+119
-39
lines changed

4 files changed

+119
-39
lines changed

‎deps/homalg-project.jl‎

Lines changed: 73 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,31 @@
11
global HOMALG_PROJECT_PATH = dirname(@__DIR__)
22

3-
##
3+
"""
4+
HomalgProject.PKG_DIR
5+
6+
The directory in which to install bundled
7+
[GAP](https://www.gap-system.org) packages from the github organization
8+
[https://github.com/homalg-project/](https://github.com/homalg-project/).
9+
It is equal to `joinpath(pathof(HomalgProject),"pkg")`.
10+
"""
11+
global PKG_DIR = joinpath(HOMALG_PROJECT_PATH, "pkg")
12+
13+
"""
14+
DownloadPackageFromHomalgProject(pkgname)
15+
16+
Clone the package named `pkgname` from the github organization
17+
[https://github.com/homalg-project/](https://github.com/homalg-project/) to the subdirectory
18+
[`HomalgProject.PKG_DIR`](@ref).
19+
On success return `true` and on failure `false`.
20+
"""
421
function DownloadPackageFromHomalgProject(pkgname)
522

623
res = GAP.Globals.LoadPackage(julia_to_gap("PackageManager"), false)
724
@assert res
8-
dir = HOMALG_PROJECT_PATH * "/pkg/"
925
git = julia_to_gap("git")
1026
clone = julia_to_gap("clone")
1127

12-
dir = dir * pkgname
28+
dir = joinpath(PKG_DIR, pkgname)
1329

1430
if isdir(dir)
1531
return true
@@ -31,16 +47,24 @@ end
3147

3248
export DownloadPackageFromHomalgProject
3349

34-
##
50+
"""
51+
UpdatePackageFromHomalgProject(pkgname)
52+
53+
Update the package named `pkgname` located in the subdirectory
54+
[`HomalgProject.PKG_DIR`](@ref) from the github organization
55+
[https://github.com/homalg-project/](https://github.com/homalg-project/).
56+
If the package directory does not exist locally then invoke
57+
[`DownloadPackageFromHomalgProject`](@ref)(`pkgname`).
58+
On success return `true` and on failure `false`.
59+
"""
3560
function UpdatePackageFromHomalgProject(pkgname)
3661

3762
res = GAP.Globals.LoadPackage(julia_to_gap("PackageManager"), false)
3863
@assert res
39-
dir = HOMALG_PROJECT_PATH * "/pkg/"
4064
git = julia_to_gap("git")
4165
pull = julia_to_gap("pull")
4266

43-
dir = dir * pkgname
67+
dir = joinpath(PKG_DIR, pkgname)
4468

4569
if !isdir(dir)
4670
return DownloadPackageFromHomalgProject(pkgname)
@@ -62,16 +86,22 @@ end
6286

6387
export UpdatePackageFromHomalgProject
6488

65-
##
89+
"""
90+
RemovePackageFromHomalgProject(pkgname)
91+
92+
Delete the package named `pkgname` from the subdirectory
93+
[`HomalgProject.PKG_DIR`](@ref).
94+
On success return `true` and on failure `false`.
95+
Removing a package and re-downloading it might be useful if udpating it fails.
96+
"""
6697
function RemovePackageFromHomalgProject(pkgname)
6798

6899
res = GAP.Globals.LoadPackage(julia_to_gap("PackageManager"), false)
69100
@assert res
70-
dir = HOMALG_PROJECT_PATH * "/pkg/"
71101
rm = julia_to_gap("rm")
72102
opt = julia_to_gap("-rf")
73103

74-
dir = dir * pkgname
104+
dir = joinpath(PKG_DIR, pkgname)
75105

76106
if !isdir(dir)
77107
return false
@@ -143,8 +173,22 @@ global PACKAGES_BASED_ON_CAP = [
143173
"ZariskiFrames",
144174
]
145175

176+
"""
177+
HomalgProject.PACKAGES_TO_DOWNLOAD
178+
179+
List of packages which will be considered by
180+
* [`DownloadAllPackagesFromHomalgProject`](@ref)()
181+
* [`UpdateAllPackagesFromHomalgProject`](@ref)()
182+
* [`RemoveAllPackagesFromHomalgProject`](@ref)()
183+
"""
146184
global PACKAGES_TO_DOWNLOAD = vcat(PACKAGES_BASED_ON_HOMALG, PACKAGES_BASED_ON_CAP)
147185

186+
"""
187+
DownloadAllPackagesFromHomalgProject()
188+
189+
Apply [`DownloadPackageFromHomalgProject`](@ref) to all packages
190+
listed in [`PACKAGES_TO_DOWNLOAD`](@ref).
191+
"""
148192
function DownloadAllPackagesFromHomalgProject()
149193

150194
for pkg in PACKAGES_TO_DOWNLOAD
@@ -155,6 +199,12 @@ end
155199

156200
export DownloadAllPackagesFromHomalgProject
157201

202+
"""
203+
UpdateAllPackagesFromHomalgProject()
204+
205+
Apply [`UpdatePackageFromHomalgProject`](@ref) to all packages listed
206+
in [`PACKAGES_TO_DOWNLOAD`](@ref).
207+
"""
158208
function UpdateAllPackagesFromHomalgProject()
159209

160210
for pkg in PACKAGES_TO_DOWNLOAD
@@ -165,6 +215,12 @@ end
165215

166216
export UpdateAllPackagesFromHomalgProject
167217

218+
"""
219+
RemoveAllPackagesFromHomalgProject()
220+
221+
Apply [`RemovePackageFromHomalgProject`](@ref) to all packages listed
222+
in [`PACKAGES_TO_DOWNLOAD`](@ref).
223+
"""
168224
function RemoveAllPackagesFromHomalgProject()
169225

170226
for pkg in PACKAGES_TO_DOWNLOAD
@@ -175,6 +231,14 @@ end
175231

176232
export RemoveAllPackagesFromHomalgProject
177233

234+
"""
235+
HomalgProject.PACKAGES_TO_COMPILE
236+
237+
The list of all [GAP](https://www.gap-system.org) packages that will
238+
downloaded (once) and installed by `GAP.Packages.install` when `using
239+
Pkg; Pkg.build("HomalgProject")` is invoked. The latter should be
240+
called once `GAP.jl` gets updated.
241+
"""
178242
global PACKAGES_TO_COMPILE = [
179243
"Gauss",
180244
#"Browse", ## do not compile browse as it results into GAP raising the error "Error opening terminal: xterm-256color."

‎docs/src/examples.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ The following examples tests the functionality of the software projects
99
```@meta
1010
DocTestSetup = quote
1111
using HomalgProject
12-
GAP.Globals.SizeScreen( julia_to_gap( [ 4096 ] ) )
12+
SizeScreen( [ 2^12 ] )
1313
LoadPackage( "GradedModules" )
1414
LoadPackage( "GradedModulePresentationsForCAP" )
1515
GAP.Globals.HOMALG_IO.show_banners = false

‎docs/src/index.md‎

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# HomalgProject.jl
22

3+
```@meta
4+
CurrentModule = HomalgProject
5+
```
36
## Introduction
47

58
The [Julia](https://julialang.org/) package `HomalgProject` provides simplified access to the repositories of the [GAP](https://www.gap-system.org) packages hosted at the GitHub organization [homalg-project](https://github.com/homalg-project), most of which are based on the
@@ -18,27 +21,35 @@ $ julia
1821
julia> using Pkg; Pkg.add("HomalgProject")
1922
```
2023

21-
This will also clone the repositories listed in `HomalgProject.PACKAGES_TO_DOWNLOAD` using `DownloadAllPackagesFromHomalgProject( )` and compile the packages listed in `HomalgProject.PACKAGES_TO_COMPILE` using `GAP.Packages.install( pkgname )`.
22-
23-
Furthermore:
24-
25-
* `UpdateAllPackagesFromHomalgProject( )` updates all packages listed in `HomalgProject.PACKAGES_TO_DOWNLOAD` using `UpdatePackageFromHomalgProject( pkgname )`.
26-
27-
* `RemoveAllPackagesFromHomalgProject( )` removes all packages listed in `HomalgProject.PACKAGES_TO_DOWNLOAD` using `RemovePackageFromHomalgProject( pkgname )`. This might be useful if you encounter problems while updating the packages.
24+
## Testing
2825

2926
The correctness of the installation and the availability of the functionality can at any time be tested using
3027

3128
```julia
3229
julia> using Pkg; Pkg.test("HomalgProject")
3330
```
3431

35-
After each update of the Julia package `GAP` a rebuild is (probably) necessary:
32+
## Updating
3633

3734
```julia
38-
julia> using Pkg; Pkg.build("HomalgProject")
35+
julia> using Pkg; Pkg.update("HomalgProject")
36+
julia> Pkg.build("HomalgProject")
3937
```
4038

41-
This will eventually (re)compile the packages listed in `HomalgProject.PACKAGES_TO_COMPILE`.
39+
This will also clone the repositories listed in [`HomalgProject.PACKAGES_TO_DOWNLOAD`](@ref) using [`DownloadAllPackagesFromHomalgProject`](@ref) and compile the packages listed in [`HomalgProject.PACKAGES_TO_COMPILE`](@ref) using `GAP.Packages.install`(`pkgname`).
40+
41+
```@docs
42+
version
43+
PKG_DIR
44+
PACKAGES_TO_DOWNLOAD
45+
DownloadAllPackagesFromHomalgProject
46+
UpdateAllPackagesFromHomalgProject
47+
RemoveAllPackagesFromHomalgProject
48+
DownloadPackageFromHomalgProject
49+
UpdatePackageFromHomalgProject
50+
RemovePackageFromHomalgProject
51+
PACKAGES_TO_COMPILE
52+
```
4253

4354
## Software dependency
4455

@@ -52,7 +63,7 @@ This will eventually (re)compile the packages listed in `HomalgProject.PACKAGES_
5263

5364
all of which are components of the computer algebra system [OSCAR](https://oscar.computeralgebra.de/).
5465

55-
Some of the bundled packages use the GAP packages
66+
Some of the bundled packages use the [GAP](https://www.gap-system.org) packages
5667

5768
* [IO](https://github.com/gap-packages/io/)
5869
* [ferret](https://github.com/gap-packages/ferret/)
@@ -72,11 +83,13 @@ and the
7283

7384
The software comes with absolutely no warranty and will most likely have errors. If you use it for computations, please check the correctness of the result very carefully.
7485

75-
This software is licensed under the LGPL, version 3, or any later version.
86+
This software is licensed under the [LGPL, version 3](https://www.gnu.org/licenses/lgpl-3.0.en.html), or any later version.
7687

7788
## Funding
7889

7990
*The development of both software projects was partially funded by the [DFG (German Research Foundation)](https://www.dfg.de/) through the [Special Priority Project SPP 1489](https://spp.computeralgebra.de/) and the [Transregional Collaborative Research Centre SFB-TRR 195](https://www.computeralgebra.de/sfb/).*
8091

92+
## Index
93+
8194
```@index
8295
```

‎src/HomalgProject.jl‎

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -48,16 +48,15 @@ This software is licensed under the LGPL, version 3, or any later version.
4848
4949
## Funding
5050
51-
*The development of both software projects was partially funded by the
52-
DFG (German Research Foundation) through the [Special Priority Project
53-
SPP 1489](https://spp.computeralgebra.de/) and the [Transregional
54-
Collaborative Research Centre SFB-TRR
55-
195](https://www.computeralgebra.de/sfb/).*
51+
The development of both software projects was partially funded by the DFG (German Research Foundation) through
52+
the [Special Priority Project SPP 1489](https://spp.computeralgebra.de/) and
53+
the [Transregional Collaborative Research Centre SFB-TRR 195](https://www.computeralgebra.de/sfb/).
5654
5755
More information and the online documentation can be found at the source code repository
5856
5957
https://github.com/homalg-project/HomalgProject.jl
60-
""" module HomalgProject
58+
"""
59+
module HomalgProject
6160

6261
greet() = print("The homalg project compatibility package for Julia")
6362

@@ -168,37 +167,41 @@ end
168167

169168
export UseExternalSingular
170169

170+
"""
171+
HomalgProject.version
172+
173+
The version number of the loaded `HomalgProject`.
174+
Please mention this number in any bug report.
175+
"""
176+
global version = 0
177+
171178
if VERSION >= v"1.4"
172179
deps = Pkg.dependencies()
173180
if Base.haskey(deps, Base.UUID("50bd374c-87b5-11e9-015a-2febe71398bd"))
174181
ver = Pkg.dependencies()[Base.UUID("50bd374c-87b5-11e9-015a-2febe71398bd")]
175182
if occursin("/dev/", ver.source)
176-
global VERSION_NUMBER = VersionNumber("$(ver.version)-dev")
183+
version = VersionNumber("$(ver.version)-dev")
177184
else
178-
global VERSION_NUMBER = VersionNumber("$(ver.version)")
185+
version = VersionNumber("$(ver.version)")
179186
end
180187
else
181-
global VERSION_NUMBER = "not installed"
188+
version = "not installed"
182189
end
183190
else
184191
deps = Pkg.API.__installed(Pkg.PKGMODE_MANIFEST) #to also get installed dependencies
185192
if haskey(deps, "HomalgProject")
186193
ver = deps["HomalgProject"]
187194
dir = dirname(@__DIR__)
188195
if occursin("/dev/", dir)
189-
global VERSION_NUMBER = VersionNumber("$(ver)-dev")
196+
version = VersionNumber("$(ver)-dev")
190197
else
191-
global VERSION_NUMBER = VersionNumber("$(ver)")
198+
version = VersionNumber("$(ver)")
192199
end
193200
else
194-
global VERSION_NUMBER = "not installed"
201+
version = "not installed"
195202
end
196203
end
197204

198-
global HOMALG_VERSION_NUMBER = VERSION_NUMBER
199-
200-
export HOMALG_VERSION_NUMBER
201-
202205
function __init__()
203206

204207
DownloadPackageFromHomalgProject("homalg_project")
@@ -242,7 +245,7 @@ function __init__()
242245

243246
if show_banner
244247
print("HomalgProject v")
245-
printstyled("$VERSION_NUMBER\n", color = :green)
248+
printstyled("$version\n", color = :green)
246249
println("Imported OSCAR's components GAP, Nemo, and Singular")
247250
println("Type: ?HomalgProject for more information")
248251
end

0 commit comments

Comments
 (0)