Corndog v1.1.0
Ketchup v1.5.1
Charles Koch - November 17, 2017
Overview
Corndog with Ketchup is a combination of tools that allows quick and simple creation of source code documentation.
Corndog
A plain text extraction tool. Corndog uses a special "corndog" marker ( -== ) in text and source code files to extract sections of text and output them to a console or file.
Corndog can parse the following file formats:
| Type | File Extension | Type | File Extension |
|---|
| Plain text | .txt | XML | .xml |
| Python | .py | HTML | .html |
| Java | .java | CSS | .css |
| SQL | .sql | PHP | .php |
| C/C++ | .c / .cpp | JavaScript | .js |
| TaskBuilder | .tas | FreeMarker | .ftl |
| Properties | .properties | Bash shell script | .sh |
| Ketchup | .kp | Windows Batch file | .bat |
Usage
To capture text from a file, place a "corndog" marker ( -== ) in front of the text you wish to capture. Corndog will capture all text after the -== symbol until it hits a newline or another -== symbol.
To preserve leading whitespace, use a double forward slash ( // ) in front of the whitespace you want to keep. By default, Corndog will remove all leading whitespace.
Corndog can be run from a command line with the following command:
python3 corndog.py -hfrm -s <start_point> -n <output_name> -x <output_extension> -o <output_directory>
| Option | Description |
|---|
| -h | Display the help text. |
| -f | Output to a single file. Use with the -n and -x options to set a name and file extension for the output file. |
| -r | Recursive search. If the start_point provided by the -s option is a directory, a recursive search will also search each subdirectory. |
| -m | Output to multiple files, with each file corresponding to a source file. The files are named the same as the source file with the subfolders prepended by hyphens (-) and the extension .txt . The names cannot be set with the -n option, but the extension can be changed with the -x option. |
| -s | The starting point of the search. If the start_point provided is a file, Corndog will only parse that single file. If the strat_point is a directory, it will parse every file in the directory. Use with the -r option to make the search recursive. |
| -n | The name of the resulting parsed file. This option is only relevant if the -f option is used. |
| -x | The file extension for the resulting file(s). This option is only relevant if the -f or -m option is used. |
| -o | The directory to place the resulting output file(s). This option is only relevant if the -f or -m option is used. |
Ketchup
A special markup language designed for documenting code. It includes many specialized tags, as well as some wiki-like markup.
Ketchup can read any text-based file, but the convention is to use the .kp file extension for files that contain Ketchup tags.
Usage
Ketchup can be run from a command line with the following command:
python3 ketchup.py <filepath> -h -w -p <page_name> -n <output_name> -o <output_directory> -c <css_file>
| Option | Description |
|---|
| -h | Display the help text. |
| -p | The name of the rendered HTML page. If the name has periods, the page title will be only the right-most portion, but the full .page_name will display on the HTML page itself. |
| -n | The name of the rendered HTML file. |
| -o | The directory to place the rendered HTML file. |
| -c | Replaces the default CSS with the stylesheet specified. |
| -w | Automatically run Ketchup rendering whenever changes are detected in the file. |
Using Corndog with Ketchup
You can use Corndog with Ketchup with the following command
python3 candk.py -hfrm -s <start_point> -n <output_name> -o <output_directory>
| NOTE: | This script does give you options for the Corndog parsing, but it does not give you any options for Ketchup. It will do its file naming and titling based on the name of the source files. |
Ketchup Markup Guide
Ketchup can read any text-based file, but the convention is to use the .kp file extension for files that contain Ketchup tags.
Ketchup generally reads a file top-to-bottom, and splits the file into sections. A new section is marked by an empty line or a tag, which always starts with an "at" symbol ( @ ). Ketchup does not preserve whitespace (multiple spaces, newlines, and tabs) unless a tag is specifically made to do so. There are 3 types of markup in Ketchup: inline, frontline, and tags.
One key difference from other markup languages is that Ketchup tags cannot be nested. You cannot put a @table tag inside a @return tag. You can, however, nest inline markup inside other inline markup or in frontline markup as well as certain tags.
Inline Markup
Inline markup is markup that can occur anywhere in a line of text, even within some tags.
\ (backslash)
The backslash will let you escape any character that would normally be used by Ketchup for inline or frontline markup.
Markup:
Email: charles\@cerrax.com
Render:
Email: charles@cerrax.com
@ (line break)
The line break lets you insert a newline in a tag that normally wouldn't let you have one.
Markup:
I like this place@
@
But I don't@
want to
be here anymore.@
Good-bye!
Render:
I like this place
But I don't
want to be here anymore.
Good-bye!
/ (code)
Very often when documenting source code, you'll want to reference a variable name or a method. To make these references stand out and avoid confusion when the name is a very common word, use the forward slash (known as the code markup) to mak the word directly following it styled in a monospace font that is similar to how most IDE's display source code.
| NOTE: | Other inline markups (bold, italic, codeline, and line break) will not be applied to the word styled by this markup. |
Markup:
When testing this method, set the /startTime value to 0 for best results.
Render:
When testing this method, set the startTime value to 0 for best results.
/- -/ (codeline)
When documenting code, it may be useful to provide short snippets of code. Whereas the forward slash provides a single word with the appropriate styling, the codeline markup provides a way to mark a whole string as a code segment.
| NOTE: | Other inline markups (bold, italic, code, and line break) will not be applied to the word styled by this markup. |
Markup:
The function will exit the loop prematurely if /-num_parkas/1.2 <= 3-/ and you initialize the rainstorm.
Render:
The function will exit the loop prematurely if num_parkas/1.2 <= 3 and you initialize the rainstorm.
! (hyperlink)
When you need to provide a link, use an exclamation mark (!) at teh bgeinning of the link to make it clickable.
| NOTE: | Other inline markups (bold, italic, code/codeline, and line break) will not be applied to the word styled by this markup. |
Markup:
Follow the yellow brick road: !http://www.cerrax.com
Render:
*bold*
To mark a string as bolded style, place asterisks on either side. Make sure there isn't any space between the asterisk and the first character, or the styling will not take effect.
Markup:
"You don't understand!" he cried, "You *really* won't like me when I'm angry..."
Render:
"You don't understand!" he cried, "You really won't like me when I'm angry..."
_italics_
To mark a string as italic style, place a single underscore on either side. Make sure there isn't any space between the underscore and the first character, or the styling will not take effect.
Markup:
"Miss, don't be alarmed, but the call is coming _from inside the house._" the police officer said.
Render:
"Miss, don't be alarmed, but the call is coming from inside the house." the police officer said.
Frontline Markup
Frontline markup is markup that only applies if it is the first mark on a line. Frontline markup can contain inline markup, but it cannot contain tags or other frontline markup.
- (unbulleted list)
To make a list that has no bullet points next to the list items, place hyphens with a space after to create a list. The more hyphens you add, the deeper the list (to a maximum of 4).
Markup:
- This is a list
- *It has items* in it. Some items
Are more fun than others
But it's all in good fun.
-- This is a _deeper list_
--- Even /deeper still. Pretty neat huh?
It is a marvelous world
- Now /-we're back to the first-\ level
--- And we can jump to the third!
Render:
- This is a list
- It has items in it. Some items Are more fun than others But it's all in good fun.
- This is a deeper list
- Even deeper still. Pretty neat huh? It is a marvelous world
- Now we're back to the first- level
- And we can jump to the third!
* (bulleted list)
To make a list with bullet points, place asterisks with a space after to create a list. The more asterisks you add, the deeper the list (to a maximum of 4).
Markup:
* This is a bulleted list!
** See how deep it gets!
*** Yowza!
**** Level four
Render:
# (numbered list)
To make an ordered list, place hash marks with a space after to create a list. The more hash marks you add, the deeper the list (to a maximum of 4).
Markup:
# Numbered list
# See it counting up?
## Second level
### How deep does
the rabbot hole go?
#### Pretty deep actually
## Wow
# Pretty cool
Render:
- Numbered list
- See it counting up?
- Second level
- How deep does the rabbot hole go?
- Pretty deep actually
- Wow
- Pretty cool
Tags
Every tag in Ketchup is marked with an "at" symbol ( @ ). Tags must be on their own line. Each line after the tag is considered part of that tag. Once an empty line or another tag is encountered, the tag will close.
| NOTE: | Ketchup cannot nest tags and tags cannot contain frontline markup. However, tags can contain inline markup. |
@page
By default, Ketchup uses the source filepath as the page name. The filename is used for the HTML <title> tag and the full filepath is the title displayed on the page.
Markup:
@page
directory.another_dir.module
Render:
The page will render with module as the name displayed in the tab of the browser and directory.another_dir.module in the black title bar across the top of the page. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.
@file
Defines the filename that this document should have.
| NOTE: | Only valid file names will work. Invalid file names will cause Ketchup to throw an exception. |
Markup:
@file
Output-File-name
Render:
This will create an HTML file named Output-File-name.html
@outdir
Defines the filepath to place the rendered HTML file.
| NOTE: | It is recommended to use an absolute filepath. This is because a relative filepath with start from the start_point provided to Ketchup and thus the correct path cannot be guaranteed. |
Markup:
@outdir
/Users/user1/Documents/Ketchup-Docs
Render:
This will save the rendered HTML in a file at /Users/user1/Documents/Ketchup-Docs .
@byline
Any information that pertains to the authorship, ownership, or relationship of a section should be placed in a @byline tag. This is a multi-line tag, meaning that each line will stay on its own line.
Markup:
@byline
Project Awesome v1.3.76
Charlie Koch - January 25, 2016
Render:
Project Awesome v1.3.76
Charlie Koch - January 25, 2016
@imports
Any modules or other code that is needed for this code to work (e.g. Java import , or C/C++ include , or HTML <link> or <script> tags). This is a multi-line tag, meaning that each line will stay on its own line.
Markup:
@imports
import os, sys
from module.another_module.file import MyClass, BetterClass
from module.different_module.file2 import Class2
Render:
Imports:
import os, sys
from module.another_module.file import MyClass, BetterClass
from module.different_module.file2 import Class2
@class
Marks the following line(s) as the header of a class. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.
This tag also creates an entry in the navigation sidebar.
| NOTE: | Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag. |
Markup:
@class
public GreatObject extends AnotherObject
implements AnInterface
Render:
public GreatObject extends AnotherObject implements AnInterface
@method
Marks the following line(s) as the header of a function or method. This is a single-line tag, meaning that multiple lines will be concatenated into a single line.
This tag also creates an entry in the navigation sidebar.
| NOTE: | Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag. |
Markup:
@method
def prepareLaunch(power, payload,
vector1, vector2,
spaceship, fuel_type)
Render:
def prepareLaunch(power, payload, vector1, vector2, spaceship, fuel)
@deflist
Creates a table with names and their descriptions. Each line is a row of the table in the format: def_name: Description of the definition . The def_name section ignores all markup. The description allows inline markup.
The @attributes , @params , @constants , and @exceptions tags do the same formatting with special headers attached.
Markup:
@deflist
definition: this is a definition
def2: this is another def
whoa: this is cool
@attributes
str: The string to search
chars: Number of characters to search
variable_name: Description
@constants
MAX_RETRIES: Maximum number of retries to
attempt before quitting
TIMEOUT: Time in seconds before the communication should end
SUCCESS_STRING: The string that prints if successful
@params
start_time: Time when this function started
end_time: Time when this function should end
filepath: Where this function should place the output
@exceptions
DataAccessError: database access error
BusinessLogicError: when something violates the rules
Render:
| definition | this is a definition |
| def2 | this is another def |
| whoa | this is cool |
Attributes:
| str | The string to search |
| chars | Number of characters to search |
| variable_name | Description |
Constants:
| MAX_RETRIES | Maximum number of retries to attempt before quitting |
| TIMEOUT | Time in seconds before the communication should end |
| SUCCESS_STRING | The string that prints if successful |
Parameters:
| start_time | Time when this function started |
| end_time | Time when this function should end |
| filepath | Where this function should place the output |
DataAccessError: database access error BusinessLogicError: when something violates the rules
@return
A small section that details the return value of a method or function.
This is a single-line tag, meaning that multiple lines will be concatenated into a single line.
Markup:
@return
A small integer, but not too small. But just right.
Ask Goldilocks about it...
Render:
Returns:
A small integer, but not too small. But just right. Ask Goldilocks about it...
@h1, @h2, @h3, @h4
Standard wiki-like header tags. The smaller the number, the larger the text.
These tags also create an entry in the navigation sidebar.
| NOTE: | Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag. |
Markup:
@h1
Header 1
@h2
Header 2
@h3
Header 3
@h4
Header 4
Render:
Header 1
Header 2
Header 3
Header 4
@m1, @m2, @m3, @m4
Standard wiki-like header tags. The smaller the number, the larger the text.
These tags do not create an entry in the navigation sidebar.
| NOTE: | Inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag. |
Markup:
@m1
Marker 1
@m2
Marker 2
@m3
Marker 3
@m4
Marker 4
Render:
Marker 1
Marker 2
Marker 3
Marker 4
@table
A simple table element. Because Ketchup can't nest tags, you cannot use any tags inside the table. However, inline markup still works.
Each line is a row of the table. Each column is separated by a pipe ( | ), but there are no pipes on the ends of the row. The first row is the header row. The next row is a row of at least 3 hyphens ( --- ) to mark the end of the header. Each row after that is a simple row of the table.
Markup:
@table
Column 1 | Column 2 | Column 3
-----------------------------------------
Data in here | more |
| Stuff | More data in here!
Data? | | Even more!
Render:
| Column 1 | Column 2 | Column 3 |
|---|
| Data in here | more | |
| Stuff | More data in here! |
| Data? | | Even more! |
@br
A sort-of line break (hence the "br") that provides extra whitespace between elements.
Markup:
Section
Another section
This is a section@with an inline break.
@br
And this a line break!
Render:
Section
Another section
This is a section
with an inline break.
And this a line break!
@hr ___
A horizontal rule, useful for separating sections to improve readability. An alternate markup for the horizontal rule is 3 underscores ( ___ ) though anything more than 3 will work.
Markup:
Using the /\@hr tag
@hr
Using the /___ markup
___
Using a longer underscore markup
____________________________
Render:
Using the @hr tag
Using the ___ markup
Using a longer underscore markup
@codeblock
Since the inline markup for code and codeline only works on a single line and doesn't preserve whitespace, this tag provides exactly than for larger sectiosn of code. Because of this, it requires a second tag at the end of the block: @endcodeblock .
| NOTE: | As with all code markup, inline markups (bold, italic, code, and line break) will not be applied to text styled by this tag. |
Markup:
@codeblock
There's code in here.
Lots of code.
So much code!
For real, this is crazy.
@endcodeblock
Render:
There's code in here.
Lots of code.
So much code!
For real, this is crazy.
@literal
Similar to the codeblock, but still renders the text in regular section rather than monspace. Usually HTML will collapse all whitespace into a single space character, so keep that in mind when using this tag. It's mainly for entering large sections of text that may contain many characters and tags that are used by Ketchup. Can also be used to insert HTML or other markup languages in a Ketchup document.
Markup:
@literal
This is a literal
@br
There's some crazy /stuff _in this tag_
but Ketchup *won't render any of it*.
# List
## Numbered list
@endliteral
Render:
This is a literal
@br
There's some crazy /stuff _in this tag_
but Ketchup *won't render any of it*.
This is a div
# List
## Numbered list
@note
Inserts a special note section that can used to bring a specific section to the reader's attention or add a significant footnote. The italic inline markup does appear to change the style of the text since this tag makes text italic by default.
This is a single-line tag, meaning that multiple lines will be concatenated into a single line.
Markup:
@note
You must be careful. _*Never*_ underestimate
the power of the /-Dark Side-/.
Render:
| NOTE: | You must be careful. Never underestimate the power of the Dark Side. |
Generated 09:32AM 05 Dec 2017Documentation generated by Ketchup v1.5.1Developed by Charles Koch - 2017