Version: 4.2.2
3 Package Utilities
| (require (planet orseau/lazy-doc:1:0/package)) |
This module provides definitions to easily create PLaneT packages along with their documentation (using the automatic scribble parser, see defs-parser).
All the functions of this module are meant to be used when current-directory is correctly set to the directory of your package. This is generally true when evaluating a file of your package in DrScheme.
3.1 A Simple Example
The best way to see what this package does is to test by yourself.
Create a directory "my-package", then create inside this directory a "my-module.ss" file (in plain text, without comment boxes). In this module, create a few simple functions and execute this file in DrScheme (F5). In the interaction window, evaluate:
(require (schememodname/this-package package))
Then evaluate:
You have now a (poorly documented, but still documented) ready-to-send package.
You can look at the generated documentation in the "planet-docs" sub-directory
(view "index.html" in a Web browser).
See the functions below for more details on the possible options when creating packages.
Modules can of course be much more documented while keeping most of the
process automatic. See Scribble Definition Parser for documenting
source files.
You can create several modules, all will be automatically included and
documented (an exception list be given).
| (package-name) → string? |
| (package-name name) → void? |
| name : string? |
A parameter controlling the name of the patckage.
By default it is the name of the current directory.
| (major-version) → number? |
| (major-version number) → void? |
| number : number? |
A parameter controlling the major-version number of the current package (default: 1).
| (minor-version) → number? |
| (minor-version number) → void? |
| number : number? |
A parameter controlling the minor-version number of the current package (default: 0).
| (package-username) → string? |
| (package-username username) → void? |
| username : string? |
A parameter controlling the username number of the current package
By default it is the username of the OS environment.
| (planet-create) → void? |
Launches the "planet" executable with the "create" option.
I prefer this solution to make-planet-archive because
it seems to provide more debug info.
| |||||||||||||||||||||
| package-name : string? | |||||||||||||||||||||
| filename : string? | |||||||||||||||||||||
| extension : string? = "ss" |
Creates the whole scribble string associated
with filename, automatically looking for the provided definitions
(using quote-require).
| (write-doc file [dir #:exists exists]) → void? | ||||||||||||
| file : string? | ||||||||||||
| dir : (or/c path-string? 'up 'same) = 'same | ||||||||||||
|
Writes the ".scrbl" file asociated with file in the directory dir.
The exists argument is the same as for with-output-to-file, and
the dir argument is the same as for build-path.
| (write-main-src main files [#:exists exists]) → void? | ||||||||||||
| main : path-string? | ||||||||||||
| files : (listof path-string?) | ||||||||||||
|
(Re)writes the main source file of the package, using require-provide
for each file of the package.
| ||||||||||||||||||||||||||||
| main : path-string? | ||||||||||||||||||||||||||||
| dir : (or/c path-string? 'up 'same) | ||||||||||||||||||||||||||||
| files : (listof path-string?) | ||||||||||||||||||||||||||||
|
Writes the main ".scrbl" file in the dir directory with a table of contents.
If exists is 'error, write-main-doc only displays
a warning and does not overwrite the file.
If modules have been added to the package since the last
execution of (planet-build),
either the user should delete the main file so that it will be rewritten,
or the user should add the inclusion of the modules himself in the
main file.
| ||||||||||||||||||||||||||||
| dir : (or/c path-string? 'up 'same) | ||||||||||||||||||||||||||||
| main-src : string? | ||||||||||||||||||||||||||||
| main-doc : string? | ||||||||||||||||||||||||||||
|
Writes a stub of the the "info.ss" file that ought to be modified
by the user.
The argument dir is the sub-directory of the documentation.
See write-main-doc for information about the exists option.
| |||||||||||||||||||||||||||||||||||
| dir : path-string? = "reference" | |||||||||||||||||||||||||||||||||||
| main-src : (or/c #f string?) = "main.ss" | |||||||||||||||||||||||||||||||||||
| main-doc : (or/c #f string?) = "manual" | |||||||||||||||||||||||||||||||||||
| info? : boolean? = #t | |||||||||||||||||||||||||||||||||||
| except : (listof string?) = '() |
Calls write-main-src on main-src, write-main-doc on main-doc,
if they are provided.
Calls write-info if info? is #t, and creates the documentation
directory dir if it does not already exist.
(Re)writes the ".scrbl" file for all other ".ss" or ".scm" file in the directory (but not in sub-directories), without warning. An exception list of files that must not be included in the process can be given through except.
Deletes all ".bak" files, in the current directory and
its sub-directories, that may have been created by DrScheme.
Creates a PLaneT hard link to the current directory
so that it is considered as a package.
Removes the planet hard link of the current package.
| |||||||||||||||||||||||||||||||||||
| dir : path-string? = "reference" | |||||||||||||||||||||||||||||||||||
| main-src : (or/c #f string?) = "main.ss" | |||||||||||||||||||||||||||||||||||
| main-doc : (or/c #f string?) = "manual" | |||||||||||||||||||||||||||||||||||
| info? : boolean? = #t | |||||||||||||||||||||||||||||||||||
| except : (listof string?) = '() |
Creates a hard-link,
calls write-docs with the except exception list of files,
calls delete-bak-files, and then calls planet-create.
See write-docs for the description of the keyword options.