Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cyevgeniy/pldoc
Documentation generator for Oracle PL/SQL
https://github.com/cyevgeniy/pldoc
pl-sql plsql plsql-docs plsql-documentation
Last synced: 24 days ago
JSON representation
Documentation generator for Oracle PL/SQL
- Host: GitHub
- URL: https://github.com/cyevgeniy/pldoc
- Owner: cyevgeniy
- License: bsd-3-clause
- Created: 2022-06-04T22:55:43.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-22T20:38:44.000Z (about 1 month ago)
- Last Synced: 2024-11-22T21:29:17.753Z (about 1 month ago)
- Topics: pl-sql, plsql, plsql-docs, plsql-documentation
- Language: Go
- Homepage:
- Size: 41 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pldoc - documentation generator for PL/SQL
## Demo
This is the [generated documentation](https://ychbn.com/pldoc-docs/amazon_aws_s3_pkg.html)
for the [Alexandria plsql utils library](https://github.com/mortenbra/alexandria-plsql-utils).
**Note**: pldoc is under development.
Pldoc is a documentation generator for PL/SQL that is inspired by how documentation
is generated in the Go programming language. It takes source code of specification files for
PL/SQL packages and generates documentation in html format. Generated documentation can
be placed on a server or viewed locally. The source of documentation is the comments in
code. The comment that hasn't empty lines between itself and a code object (function, variable etc)
is considered as the object's documentation. For example, the next code snippet is
the function `has_permission` with its documentation:
```
-- Returns true if the user has access to perform
-- this operation.
function has_permission(user_id number, op varchar2) return boolean;
```
If there is a blank line (or lines) between a comment and an object, the comment
isn't processed as documentation:
```
-- Returns true if the user has access to perform
-- this operation.
function has_permission(user_id number, op varchar2) return boolean;
```
However, an empty line (or lines) that is the part of a comment, isn't taken into account
as a separator between documentation and an object and a whole comment
is parsed as documentation:
```
-- Returns true if the user has access to perform
-- this operation.
--
function has_permission(user_id number, op varchar2) return boolean;
```
For now, pldoc can generate docs for:
- Package documentation
- Functions, procedures
- Cursors
- Records declaration
- Varrays, tables
- Constants and variables
## Limitations
- Specification files should be in UTF-8 encoding
## Build from source
```
go build pldoc.go
```
## Usage
This command generates documentation for each file with `.pks` extension
in the `source_directory`. The documentation files will be placed in the
`documentation` directory.
```
pldoc --output=documentation source_directory
```
To change the extension of searched files, `ext` flag is used:
```
pldoc --output=documentation --ext=sql source_directory
```
Pldoc can generate docs from multiple directories, all you need is just list them with a space. Each
directory will be walked recursively, for example:
```
pldoc --output=documentation source_dir1 source_dir2 source_dir3
```
## Comment styles
It's better not to decorate you comments. Bad example:
```
/*****************************************
* This function returns the my_table row
* by its id
*****************************************/
```
Good example:
```
-- This function returns the my_table row
-- by its id
```
Another one good example:
```
/*
This function returns the my_table row
by its id
*/
```
## Preformatted text and lists
Any line that has greater indentation that comment's first line
is preformatted text.
```
-- This procedure returns formatted output of
-- passed record. It looks like this:
-- key1: value 1
-- key2: value 2
-- key3: value 3
```
In documentation, lines from 3 to 5 will be enclosed in
`pre` tag.