perl builddocs.pl

use strict;

use warnings;

use IPC::System::Simple qw(system);

use Markdent::Simple::Document;

use Markdent::Simple::Fragment;

use File::Map qw(map_file);

use File::Path qw(make_path);

use constant false => 0;

use constant true => 1;

main();

sub main{

# Create output directories if the don't exists

make_path("../docs");

# Execute NaturalDocs

# -i InputDirectory

# -o FramedHTML or HTML OutputDirectory (Using HTML so we can directly link to documenation pages easier.)

# -p ProectDirectory

# -xi ExcludeDirFromInput

# -r RebuildAllFiles

my @nd_args = qw(

);

system($^X, "../tools/ndocs/NaturalDocs", @nd_args);

#convert markdown files to html

#convert_markdown_file("../CONTRIBUTING.md","../docs/files/docsource/topics/contributing-txt.html","How to contribute to utPLSQL");

convert_markdown_and_insert("../CONTRIBUTING.md","../docs/files/docsource/topics/contributing-txt.html");

#Checking for current/past errors with NaturalDocs

check_project_file_for_error("project/Menu.txt");

check_project_file_for_error("project/Languages.txt");

check_project_file_for_error("project/Topics.txt");

if (-e "project/LastCrash.txt") {

die "project/LastCrash.txt found, indicating a prior NaturalDocs problem that should be fixed. Note: File must be manually removed to continue";

}

}

sub check_project_file_for_error {

my $file_to_check = shift;

map_file(my $menufile,$file_to_check);

if ($menufile =~ /ERROR/) { die "ERROR found $file_to_check" }

}

sub convert_markdown {

my $markdowntext = shift;

my $fragment = shift;

my $title = shift;

# convert markdown to html

my $htmltext;

if ($fragment = true) {

my $parser = Markdent::Simple::Fragment->new();

$htmltext = $parser->markdown_to_html(

markdown => $markdowntext);

} else {

my $parser = Markdent::Simple::Document->new();

$htmltext = $parser->markdown_to_html(

markdown => $markdowntext,

title => $title);

}

#return

$htmltext;

}

sub convert_markdown_and_insert {

my $source = shift;

my $dest = shift;

# memory map input file

map_file(my $markdown, $source);

# convert markdown to html

my $html = convert_markdown($markdown,true);

# read output file

open FILE, "<$dest" or die "Couldn't open file: $!";

binmode FILE;

my $output = do { local $/; <FILE> };

close FILE;

#search and replace

$output =~ s/$source/$html/g;

# write output file

open FILE, ">$dest" or die "Couldn't open file: $!";

binmode FILE;

print FILE $output;

close FILE;

}

sub convert_markdown_file {

my $source = shift;

my $dest = shift;

my $title = shift;

# memory map input file

map_file(my $markdown, $source);

# convert markdown to html

my $html = convert_markdown($markdown,false,$title);

# check output file exists, and deletes.

if (-f $dest) {

unlink $dest or die "Cannot delete $dest: $!";

}

# write markdown to file

my $OUTFILE;

open $OUTFILE, '>>', $dest or die "Cannot open $dest";

print { $OUTFILE } $html or die "Cannot write to $dest";

close $OUTFILE or die "Cannot close $dest";

print "Converted $source to $dest"

}

Format: Development Release 07-07-2013 (1.52 base)

Ignore Extension: pl

Add Extensions: pks tps

Format: Development Release 07-07-2013 (1.52 base)

Title: utPLSQL

SubTitle: v 3.0 Alpha

Footer: Copyright (c) 2016 - utPLSQL Project

Timestamp: Generated on month day, year

Group: Documentation {

File: Installation (docsource/topics/install.txt)

File: Getting Started (docsource/topics/getting-started.txt)

File: Annotations (docsource/topics/Annotations.txt)

File: Support (docsource/topics/Support.txt)

} # Group: Documentation

Group: Source {

File: ut_metadata (source/ut_metadata.pks)

File: ut_utils (source/ut_utils.pks)

File: License (source/license.txt)

File: Contributing (docsource/topics/contributing.txt)

} # Group: Source

Class Index: Classes

Constant Index: Constants

Function Index: Functions

Format: Development Release 07-07-2013 (1.52 base)

# This is the Natural Docs topics file for this project. If you change anything

# here, it will apply to THIS PROJECT ONLY. If you'd like to change something

# for all your projects, edit the Topics.txt in Natural Docs' Config directory

# instead.

# If you'd like to prevent keywords from being recognized by Natural Docs, you

# can do it like this:

# Ignore Keywords: [keyword], [keyword], ...

#

# Or you can use the list syntax like how they are defined:

# Ignore Keywords:

# [keyword]

# [keyword], [plural keyword]

# ...

#-------------------------------------------------------------------------------

# SYNTAX:

#

# Topic Type: [name]

# Alter Topic Type: [name]

# Creates a new topic type or alters one from the main file. Each type gets

# its own index and behavior settings. Its name can have letters, numbers,

# spaces, and these charaters: - / . '

#

# Plural: [name]

# Sets the plural name of the topic type, if different.

#

# Keywords:

# [keyword]

# [keyword], [plural keyword]

# ...

# Defines or adds to the list of keywords for the topic type. They may only

# contain letters, numbers, and spaces and are not case sensitive. Plural

# keywords are used for list topics. You can redefine keywords found in the

# main topics file.

#

# Index: [yes|no]

# Whether the topics get their own index. Defaults to yes. Everything is

# included in the general index regardless of this setting.

#

# Scope: [normal|start|end|always global]

# How the topics affects scope. Defaults to normal.

# normal - Topics stay within the current scope.

# start - Topics start a new scope for all the topics beneath it,

# like class topics.

# end - Topics reset the scope back to global for all the topics

# beneath it.

# always global - Topics are defined as global, but do not change the scope

# for any other topics.

#

# Class Hierarchy: [yes|no]

# Whether the topics are part of the class hierarchy. Defaults to no.

#

# Page Title If First: [yes|no]

# Whether the topic's title becomes the page title if it's the first one in

# a file. Defaults to no.

#

# Break Lists: [yes|no]

# Whether list topics should be broken into individual topics in the output.

# Defaults to no.

#

# Can Group With: [type], [type], ...

# Defines a list of topic types that this one can possibly be grouped with.

# Defaults to none.

#-------------------------------------------------------------------------------

# The following topics are defined in the main file, if you'd like to alter

# their behavior or add keywords:

#

# Generic, Class, Interface, Section, File, Group, Function, Variable,

# Property, Type, Constant, Enumeration, Event, Delegate, Macro,

# Database, Database Table, Database View, Database Index, Database

# Cursor, Database Trigger, Cookie, Build Target

# If you add something that you think would be useful to other developers

# and should be included in Natural Docs by default, please e-mail it to

# topics [at] naturaldocs [dot] org.

Contains the files needed to generated documentation. Perl is required to be able to run the generation of documentation.

#How to Run

builddocs.pl

#CPAN Modules

[CPAN Module Install Instructions](http://www.cpan.org/modules/INSTALL.html)

Required Modules:

- IPC::System::Simple

- Markdent

- File::Map

#NaturalDocs

We use NaturalDocs to generate most of the documentation.

It is linked as submodule under /tools/ndocs

Title: Annotations

Annoations are comments that control test execution. utPLSQL parses comments on a package specification only, comments in the package body are ignored.

#TODO: Add parameters, examples and sync documentation with current annotation implementation.

topic: Annotation list

%suite - Marks package to be a suite with it procedures as tests. This way all testing packages might be found in the schema. Parameter of the annotation is the Suite name

%suitepackage - Similar to java package. The example suite should be put as an element of the "globaltests" suite which is an element of the "all" suite. This allows one to execute "glovaltests" suite which would recursively run all the child suites including this one.

%suitetype - The way for suite to have something like a type. One might collect suites based on the subject of tests (a system module for example). There might be critical tests to run every time and more covering but slow tests. This technique allows to configure something like "fast" testing.

%setup - Marks procedure as a default setup procedure for the suite.

%teardown - Marks procedure as a default teardown procedure for the suite.

%test - Marks procedure as a test. Parameter is a name of the test

%testtype - Another way to tag tests to filter afterwards

%testsetup - Marks that special setup procedure has to be run before the test instead of the default one

%testteardown - Marks that special teardown procedure has to be run before the test instead of the default one

%suitesetup - Procedure with executes once at the beginning of the suite and doesn't executes before each test

%suiteteardown - Procedure with executes once after the execution of the last test in the suite.

Topic: Support

#Fill out how methods to get support.