-
Notifications
You must be signed in to change notification settings - Fork 0
Docme Syntax v2.0.1
philosowaffle edited this page Jun 19, 2014
·
1 revision
####WORK IN PROGRESS
###2.0.1
###Example Syntax
//First Element
/*
+[title]: bc_printHelloWorld
+[description]: a single line description of the function
+[summary]: {{
an example of what a multi-line
piece of content would look like.
}}
+[code]: {{
any code can go here.
<script>
alert("some js code");
</script>
}}
+[input]: {{
-[id]: takes a numeric id
-[fname]: takes a string for the first name
}}
+[anchor]: {{
-[mySecFunc]: #bc_deleteHelloWorld
-[anything]: #mustMatchTheTitleOfAnotherElement
-[funcInAnotherFile]: filename.html#FuncName
}}
+[attribute]: content
+[attribute]: {{
-[subAttribute]: single line sub content
-[subAttribute]: sub content
}}
*/
function bc_printHelloWorld( elementID ){
try{
document.getElementById( elementID ).innerHTML = "Hello World!";
} catch( error ){
logAndThrow( error, "It's possible the id you supplied does not exist." );
}
//Second Element
/*
+[title]: bc_deleteHelloWorld
+[description]: the anchor above will link to this element on the page.
+[htmlTag]: Can use html tags like so, click <a href="https://www.google.com">here</a> to go to google.
*/
function bc_deleteHelloWorld( elementID ){
try{
document.getElementById( elementID ).innerHTML = "";
} catch( error ){
logAndThrow( error, "It's possible the id you supplied does not exist." );
}###Notes
- A comment section is denoted by
/* */ - Follow the pattern of
+[attributeName]:followed by your single line content or{{for multi-line content - Sub-attributes are denoted by
-[subAttributeName]:inside of a main attribute block, sub-attributes do not support blocked content -
+[code]is a reserved word/attribute, it specifies that the following content is multi-line and will be rendered with special code formatting. -
+[anchor]is a reserved word/attribute, it specifies what other elements on the page this element relates to. The-[subAttribute]field can be anything you wish, this text will be displayed on the page. The content of each subattribute must match the content of a+[title]attribute in another element in that same file. If you wish to link to an element in another file, simply add the filename (replace the extension with.html) before the element to link to.
###Reserved Words
-
+[title]- this attribute defines the header text (or title) for the module and is also used for anchor links -
+[code]- content here will use special code formatting -
+[anchor]- the element it links to MUST have a+[title]attribute
###Docme Usage
To generate documentation, simply run the following command from the directory where your files are.
> docme
This will attempt to parse all valid files and generate a folder called docme_site containing all the web pages. You can open the index.html in any browser to view your documentation. You can also specify that docme only parse a particular file or folder using the following commands.
> docme parse <path/to/file>
OR
> docme parse <path/to/directory>
You can additionally provide your own CSS, index, or page styling for your documentation with the following command:
> docme --style myCSSStyle.erb --index myIndexLayout.erb --page myPageLayout.erb
Below is the default CSS used, you may provide your own CSS using this as a template, but ensure that you save it as a .erb file before giving it to docme.
#wrapper{
width: 70%;
padding-left: 30%;
font-size:20em;
}
#panels-wrapper{
width: 80%;
float: left;
padding-left: 10%;
}
#side-panel{
width: 15%;
float: left;
padding-left: 10px;
}
pre-scrollable{
overflow-x: scroll;
white-space: nowrap;
}
p.code{
border:1px solid #000000;
overflow-x:scroll;
white-space: pre;
font-family:monospace,monospace;
font-size:1em;
background-color:#f5f5f5;
padding:2em;
}Below is the default index used. The index page is passed an array containing pages with the attributes name and blocks.
<!DOCTYPE html>
<html>
<link href="style.css" rel="stylesheet">
<link href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet" media="screen">
<body>
<div id="wrapper">
<div class="list-group">
<% for @page in @pages %>
<a href="<%= @page.name %>.html" class="list-group-item list-group-item-info"><%= @page.name %></a>
<% end %>
</div>
</div>
</body>
</html>Below is the default page layout. Each page is passed a an array of @blocks, and an @index containing an array of all the pages. Each block in the @blocks array contains an array of @attributes.
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="style.css" rel="stylesheet">
</head>
<link href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet" media="screen">
<body>
<nav class="navbar navbar-default navbar-static-top" role="navigation">
<div class="container">
<div class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a class="navbar-brand" href="#"><%= @name%></a></li>
</ul>
</div>
</div>
</nav>
<div id="side-panel" class="panel panel-default">
<a href="index.html" class="list-group-item list-group-item-info">INDEX</a>
<% for @page in @index %>
<a class="list-group-item list-group-item-info" href="<%= @page %>.html"><%= @page %></a>
<% end %>
</div>
<div id="panels-wrapper">
<% for @block in @blocks %>
<div class="panel panel-primary">
<% @attributes = @block.attributes %>
<% for @attribute in @attributes %>
<% if @attribute[0] == "TITLE" %>
<div class="panel-heading" id="<%= @attribute[1]%>">
<h2 class="panel-title"><%= @attribute[1] %></h2>
</div>
<div class="panel-body">
<% end %>
<% if @attribute[0] == "CODE" %>
<h4>CODE</h4>
<p class="code"><%= @attribute[1] %></p>
<% end %>
<% if @attribute[0] != "TITLE" && @attribute[0] != "CODE" %>
<% if @attribute[1].class == Hash %>
<% if @attribute[0] == "ANCHOR" %>
<h4><%= @attribute[0] %></h4>
<table class="table">
<% for @item in @attribute[1]%>
<tr>
<th><%= @item[0] %></th>
<td><a href="<%= @item[1] %>"><%= @item[1] %></a></td>
</tr>
<% end %>
</table>
<% else %>
<h4><%= @attribute[0] %></h4>
<table class="table">
<% for @item in @attribute[1]%>
<tr>
<th><%= @item[0] %></th>
<td><%= @item[1] %></td>
</tr>
<% end %>
</table>
<% end %>
<% end %>
<% if @attribute[0] != "CODE" && @attribute[0] != "TITLE" && @attribute[1].class != Hash%>
<h4><%= @attribute[0]%></h4>
<p><%= @attribute[1] %></p>
<% end %>
<% end %>
<% end %>
</div>
</div>
<% end %>
</div>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
</body>
</html>If at any time you wish to remove the docme pages you can either manually delete the docme_site folder or run the following command from a location containing a folder called docme_site.
> docme clean
NOTE: This will remove ALL files in the docme_site directory and the folder itself.
###Rake Task
Require docme/rake_task
To simply execute the default docme command:
DocmeTask::RakeTask.newTo set variables:
DocmeTask::RakeTask.new(:docme) do |task|
task.parse = 'dirTest/'
task.verbose = true
task.index = 'templates/indexTest.erb'
task.page = 'templates/pageTest.erb'
task.style = 'templates/testStyle.erb'
end###Changelog