Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
82 lines (53 sloc) 2.73 KB

This file is part of Logtalk https://logtalk.org/
Copyright 1998-2018 Paulo Moura pmoura@logtalk.org

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Overview

This folder provides a simple tool for (re)generating documentation for a project. The tool defines a doclet object that is expected to be extended by the user to specify a sequence of goals and a sequence of shell commands that load the application and (re)generate its documentation.

Doclet source files are preferably named doclet.lgt (or doclet.logtalk) and the doclet object are usually named after the application or library to be documented with a _doclet suffix. By using an initialization/1 directive to automatically send the update/0 message that generates the documentation upon doclet loading, we can abstract the name of the doclet object. The usual query to load and run a doclet is therefore:

| ?- logtalk_load([doclet(loader), doclet]).

For usage examples see the sample_doclet.lgt, doclet1.lgt, zoom_doclet.lgt, and tools_doclet.lgt source files.

API documentation

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#doclet

For sample queries, please see the SCRIPT.txt file.

Loading

This tool can be loaded using the query:

| ?- logtalk_load(doclet(loader)).

Automating running doclets

You can use the scripts/logtalk_doclet.sh Bash shell script for automating running doclets. The script expects the doclet source files to be named either doclet.lgt or doclet.logtalk. See the scripts/NOTES.md file or the script man page for details.

Integration with the make tool

Loading this tool adds a definition for the logtalk_make_target_action/1 hook predicate for the target documentation. The hook definition checks that a single doclet object is loaded and, if true, sends an update/0 message to it.

Other notes

All source files are formatted using tabs (the recommended setting is a tab width equivalent to 4 spaces).