Transforms docgen sample to be generated from source.

This commit is contained in:
Grzegorz Adam Hankiewicz 2014-01-06 14:55:03 +01:00
commit 2ed7849921
5 changed files with 28 additions and 566 deletions

View file

@ -97,7 +97,7 @@ Partial Output::
proc helloWorld*(times: int) proc helloWorld*(times: int)
... ...
Output can be viewed in full here `sample.html <docgen_samples/sample.html>`_. Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
The next command, called ``doc2``, is very similar to the ``doc`` command, but The next command, called ``doc2``, is very similar to the ``doc`` command, but
will be run after the compiler performs semantic checking on the input nimrod will be run after the compiler performs semantic checking on the input nimrod
module(s), which allows it to process macros. module(s), which allows it to process macros.
@ -110,7 +110,7 @@ Partial Output::
proc helloWorld(times: int) {.raises: [], tags: [].} proc helloWorld(times: int) {.raises: [], tags: [].}
... ...
The full output can be seen here `sample2.html <docgen_samples/sample2.html>`_. The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_.
As you can see, the tool has extracted additional information provided to it by As you can see, the tool has extracted additional information provided to it by
the compiler beyond what the ``doc`` command provides, such as pragmas attached the compiler beyond what the ``doc`` command provides, such as pragmas attached
implicitly by the compiler. This type of information is not available from implicitly by the compiler. This type of information is not available from

12
doc/docgen_sample.nim Normal file
View file

@ -0,0 +1,12 @@
## This module is a sample.
import strutils
proc helloWorld*(times: int) =
## Takes an integer and outputs
## as many "hello world!"s
for i in 0 .. times-1:
echo "hello world!"
helloWorld(5)

View file

@ -1,282 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- This file is generated by Nimrod. -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Module sample</title>
<style type="text/css">
span.DecNumber {color: blue}
span.BinNumber {color: blue}
span.HexNumber {color: blue}
span.OctNumber {color: blue}
span.FloatNumber {color: blue}
span.Identifier {color: black}
span.Keyword {font-weight: bold}
span.StringLit {color: blue}
span.LongStringLit {color: blue}
span.CharLit {color: blue}
span.EscapeSequence {color: black}
span.Operator {color: black}
span.Punctation {color: black}
span.Comment, span.LongComment {font-style:italic; color: green}
span.RegularExpression {color: DarkViolet}
span.TagStart {color: DarkViolet}
span.TagEnd {color: DarkViolet}
span.Key {color: blue}
span.Value {color: black}
span.RawData {color: blue}
span.Assembler {color: blue}
span.Preprocessor {color: DarkViolet}
span.Directive {color: DarkViolet}
span.Command, span.Rule, span.Hyperlink, span.Label, span.Reference,
span.Other {color: black}
div.navigation {
-moz-border-radius: 5px 5px 5px 5px;
float: left;
width: 30%;
margin: 0; padding: 0;
border: 3px outset #7F7F7F;
background-color: #7F7F7F;
}
div.navigation ul {
list-style-type: none;
padding-left: 1em;
}
div.navigation ul li a, div.navigation ul li a:visited {
font-weight: bold;
color: #FFFFFF;
text-decoration: none;
}
div.navigation ul li a:hover {
font-weight: bold;
text-decoration: none;
color: gold;
}
div.content {
margin-left: 30%;
padding: 0 1em;
border-left: 4em;
}
dl.item dd, dl.item dd p {
margin-top:3px;
}
dl.item dd pre {
margin-left: 15pt;
border: 0px;
}
dl.item dt, dl.item dt pre {
margin: 20pt 0 0 5pt;
}
pre, span.tok {
background-color: #F9F9F9;
border-color: #C4C4C4;
border-style: solid;
border-width: 1px 1px 1px 2px;
color: black;
line-spacing: 110%;
padding: 2px;
}
span.red {
color: #A80000;
}
hr {background-color:#9D9D9D; border:0 none; color:#9D9D9D; height:1px; width:100%;}
/*
:Author: David Goodger
:Contact: goodger@python.org
:Date: Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006)
:Revision: Revision: 4564
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th { border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first { margin-top: 0 ! important }
.last, .with-subtitle { margin-bottom: 0 ! important }
.hidden { display: none }
a.toc-backref { text-decoration: none ; color: black }
blockquote.epigraph { margin: 2em 5em ; }
dl.docutils dd { margin-bottom: 0.5em }
div.abstract { margin: 2em 5em }
div.abstract p.topic-title { font-weight: bold ; text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ; border: medium outset ; padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title { font-weight: bold ; font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title { color: red ; font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication { margin: 2em 5em ; text-align: center ; font-style: italic }
div.dedication p.topic-title { font-weight: bold ; font-style: normal }
div.figure { margin-left: 2em ; margin-right: 2em }
div.footer, div.header { clear: both; font-size: smaller }
div.line-block { display: block ; margin-top: 1em ; margin-bottom: 1em }
div.line-block div.line-block { margin-top: 0 ; margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar { margin-left: 1em ; border: medium outset ;
padding: 1em ; background-color: #ffffee ; /*width: 40% ;*/ float: right ;
clear: right }
div.sidebar p.rubric { font-family: sans-serif ; font-size: medium }
div.system-messages { margin: 5em }
div.system-messages h1 { color: red }
div.system-message { border: medium outset ; padding: 1em }
div.system-message p.system-message-title { color: red ; font-weight: bold }
div.topic { margin: 2em;}
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title { text-align: center }
h2.subtitle { text-align: center }
/* hr.docutils { width: 75% } */
img.align-left { clear: left }
img.align-right { clear: right }
ol.simple, ul.simple { margin-bottom: 1em }
ol.arabic { list-style: decimal }
ol.loweralpha { list-style: lower-alpha }
ol.upperalpha { list-style: upper-alpha }
ol.lowerroman { list-style: lower-roman }
ol.upperroman { list-style: upper-roman }
p.attribution { text-align: right ; margin-left: 50% }
p.caption { font-style: italic }
p.credits { font-style: italic ; font-size: smaller }
p.label { white-space: nowrap }
p.rubric { font-weight:bold;font-size:larger;color:maroon;text-align:center}
p.sidebar-title {font-family: sans-serif ;font-weight: bold ;font-size: larger }
p.sidebar-subtitle {font-family: sans-serif ; font-weight: bold }
p.topic-title {
font-weight: bold;
background-color: #6D6D6D;
border-bottom: 1px solid #000000;
border-top: 1px solid black;
color: white;
text-align: center;
margin: 0;
}
pre.address { margin-bottom: 0;margin-top:0;font-family:serif;font-size:100% }
pre.literal-block, pre.doctest-block {margin-left: 2em ;margin-right: 2em }
span.classifier {font-family: sans-serif;font-style: oblique }
span.classifier-delimiter {font-family: sans-serif;font-weight: bold }
span.interpreted {font-family: sans-serif }
span.option {white-space: nowrap }
span.pre {white-space: pre }
span.problematic {color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation { border-left: solid 1px gray; margin-left: 1px }
table.docinfo {margin: 2em 4em }
table.docutils {margin-top: 0.5em;margin-bottom: 0.5em; border: 0 solid #9d9d9d; border-collapse: collapse; }
table.footnote {border-left: solid 1px black;margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {padding-left: 0.5em;padding-right: 0.5em;
vertical-align: top;}
table.docutils td, table.docutils th { border-bottom:1px solid #9D9D9D; }
/* color: #4d4d4d} */
/* table.docutils td:hover, table.docinfo td:hover {color: #000000} */
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold;text-align: left;white-space: nowrap;padding-left: 0 }
table.docutils th
{
color: black;
font-weight:normal;
background-color: #E3E3E3;
border-top: 1px solid #1d1d1d;
border-bottom: 1px solid #1d1d1d;
}
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {font-size: 100% }
ul.auto-toc { list-style-type: none }
/*a.reference { color: #E00000; font-weight:bold;}
a.reference:hover {color: #E00000;background-color: #ffff00;display: margin;
font-weight:bold;}*/
</style>
</head>
<body>
<div class="document" id="documentId">
<h1 class="title">Module sample</h1>
<div class="navigation" id="navigation">
<ul class="simple">
<li>
<a class="reference" href="#6" id="56">Imports</a>
<ul class="simple">
</ul>
</li>
<li>
<a class="reference" href="#12" id="62">Procs</a>
<ul class="simple">
<li><a class="reference" href="#101"><wbr />hello<wbr />World</a></li>
</ul>
</li>
</ul>
</div>
<div class="content" id="content">
This module is a sample.
<div class="section" id="6">
<h1><a class="toc-backref" href="#56">Imports</a></h1>
<dl class="item">
<a class="reference external" href="strutils.html">strutils</a>
</dl></div>
<div class="section" id="12">
<h1><a class="toc-backref" href="#62">Procs</a></h1>
<dl class="item">
<dt id="101"><pre><span class="Keyword">proc</span> <span class="Identifier">helloWorld</span><span class="Operator">*</span><span class="Other">(</span><span class="Identifier">times</span><span class="Other">:</span> <span class="Identifier">int</span><span class="Other">)</span></pre></dt>
<dd>
Takes an integer and outputs as many &quot;hello world!&quot;s
</dd>
</dl></div>
</div>
<small>Generated: 2013-12-21 11:45:42 UTC</small>
</div>
</body>
</html>

View file

@ -1,282 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- This file is generated by Nimrod. -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Module sample</title>
<style type="text/css">
span.DecNumber {color: blue}
span.BinNumber {color: blue}
span.HexNumber {color: blue}
span.OctNumber {color: blue}
span.FloatNumber {color: blue}
span.Identifier {color: black}
span.Keyword {font-weight: bold}
span.StringLit {color: blue}
span.LongStringLit {color: blue}
span.CharLit {color: blue}
span.EscapeSequence {color: black}
span.Operator {color: black}
span.Punctation {color: black}
span.Comment, span.LongComment {font-style:italic; color: green}
span.RegularExpression {color: DarkViolet}
span.TagStart {color: DarkViolet}
span.TagEnd {color: DarkViolet}
span.Key {color: blue}
span.Value {color: black}
span.RawData {color: blue}
span.Assembler {color: blue}
span.Preprocessor {color: DarkViolet}
span.Directive {color: DarkViolet}
span.Command, span.Rule, span.Hyperlink, span.Label, span.Reference,
span.Other {color: black}
div.navigation {
-moz-border-radius: 5px 5px 5px 5px;
float: left;
width: 30%;
margin: 0; padding: 0;
border: 3px outset #7F7F7F;
background-color: #7F7F7F;
}
div.navigation ul {
list-style-type: none;
padding-left: 1em;
}
div.navigation ul li a, div.navigation ul li a:visited {
font-weight: bold;
color: #FFFFFF;
text-decoration: none;
}
div.navigation ul li a:hover {
font-weight: bold;
text-decoration: none;
color: gold;
}
div.content {
margin-left: 30%;
padding: 0 1em;
border-left: 4em;
}
dl.item dd, dl.item dd p {
margin-top:3px;
}
dl.item dd pre {
margin-left: 15pt;
border: 0px;
}
dl.item dt, dl.item dt pre {
margin: 20pt 0 0 5pt;
}
pre, span.tok {
background-color: #F9F9F9;
border-color: #C4C4C4;
border-style: solid;
border-width: 1px 1px 1px 2px;
color: black;
line-spacing: 110%;
padding: 2px;
}
span.red {
color: #A80000;
}
hr {background-color:#9D9D9D; border:0 none; color:#9D9D9D; height:1px; width:100%;}
/*
:Author: David Goodger
:Contact: goodger@python.org
:Date: Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006)
:Revision: Revision: 4564
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th { border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first { margin-top: 0 ! important }
.last, .with-subtitle { margin-bottom: 0 ! important }
.hidden { display: none }
a.toc-backref { text-decoration: none ; color: black }
blockquote.epigraph { margin: 2em 5em ; }
dl.docutils dd { margin-bottom: 0.5em }
div.abstract { margin: 2em 5em }
div.abstract p.topic-title { font-weight: bold ; text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ; border: medium outset ; padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title { font-weight: bold ; font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title { color: red ; font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication { margin: 2em 5em ; text-align: center ; font-style: italic }
div.dedication p.topic-title { font-weight: bold ; font-style: normal }
div.figure { margin-left: 2em ; margin-right: 2em }
div.footer, div.header { clear: both; font-size: smaller }
div.line-block { display: block ; margin-top: 1em ; margin-bottom: 1em }
div.line-block div.line-block { margin-top: 0 ; margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar { margin-left: 1em ; border: medium outset ;
padding: 1em ; background-color: #ffffee ; /*width: 40% ;*/ float: right ;
clear: right }
div.sidebar p.rubric { font-family: sans-serif ; font-size: medium }
div.system-messages { margin: 5em }
div.system-messages h1 { color: red }
div.system-message { border: medium outset ; padding: 1em }
div.system-message p.system-message-title { color: red ; font-weight: bold }
div.topic { margin: 2em;}
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title { text-align: center }
h2.subtitle { text-align: center }
/* hr.docutils { width: 75% } */
img.align-left { clear: left }
img.align-right { clear: right }
ol.simple, ul.simple { margin-bottom: 1em }
ol.arabic { list-style: decimal }
ol.loweralpha { list-style: lower-alpha }
ol.upperalpha { list-style: upper-alpha }
ol.lowerroman { list-style: lower-roman }
ol.upperroman { list-style: upper-roman }
p.attribution { text-align: right ; margin-left: 50% }
p.caption { font-style: italic }
p.credits { font-style: italic ; font-size: smaller }
p.label { white-space: nowrap }
p.rubric { font-weight:bold;font-size:larger;color:maroon;text-align:center}
p.sidebar-title {font-family: sans-serif ;font-weight: bold ;font-size: larger }
p.sidebar-subtitle {font-family: sans-serif ; font-weight: bold }
p.topic-title {
font-weight: bold;
background-color: #6D6D6D;
border-bottom: 1px solid #000000;
border-top: 1px solid black;
color: white;
text-align: center;
margin: 0;
}
pre.address { margin-bottom: 0;margin-top:0;font-family:serif;font-size:100% }
pre.literal-block, pre.doctest-block {margin-left: 2em ;margin-right: 2em }
span.classifier {font-family: sans-serif;font-style: oblique }
span.classifier-delimiter {font-family: sans-serif;font-weight: bold }
span.interpreted {font-family: sans-serif }
span.option {white-space: nowrap }
span.pre {white-space: pre }
span.problematic {color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation { border-left: solid 1px gray; margin-left: 1px }
table.docinfo {margin: 2em 4em }
table.docutils {margin-top: 0.5em;margin-bottom: 0.5em; border: 0 solid #9d9d9d; border-collapse: collapse; }
table.footnote {border-left: solid 1px black;margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {padding-left: 0.5em;padding-right: 0.5em;
vertical-align: top;}
table.docutils td, table.docutils th { border-bottom:1px solid #9D9D9D; }
/* color: #4d4d4d} */
/* table.docutils td:hover, table.docinfo td:hover {color: #000000} */
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold;text-align: left;white-space: nowrap;padding-left: 0 }
table.docutils th
{
color: black;
font-weight:normal;
background-color: #E3E3E3;
border-top: 1px solid #1d1d1d;
border-bottom: 1px solid #1d1d1d;
}
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {font-size: 100% }
ul.auto-toc { list-style-type: none }
/*a.reference { color: #E00000; font-weight:bold;}
a.reference:hover {color: #E00000;background-color: #ffff00;display: margin;
font-weight:bold;}*/
</style>
</head>
<body>
<div class="document" id="documentId">
<h1 class="title">Module sample</h1>
<div class="navigation" id="navigation">
<ul class="simple">
<li>
<a class="reference" href="#6" id="56">Imports</a>
<ul class="simple">
</ul>
</li>
<li>
<a class="reference" href="#12" id="62">Procs</a>
<ul class="simple">
<li><a class="reference" href="#101"><wbr />hello<wbr />World</a></li>
</ul>
</li>
</ul>
</div>
<div class="content" id="content">
This module is a sample.
<div class="section" id="6">
<h1><a class="toc-backref" href="#56">Imports</a></h1>
<dl class="item">
<a class="reference external" href="strutils.html">strutils</a>
</dl></div>
<div class="section" id="12">
<h1><a class="toc-backref" href="#62">Procs</a></h1>
<dl class="item">
<dt id="101"><pre><span class="Keyword">proc</span> <span class="Identifier">helloWorld</span><span class="Other">(</span><span class="Identifier">times</span><span class="Other">:</span> <span class="Identifier">int</span><span class="Other">)</span> <span class="Other">{.</span><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">.}</span></pre></dt>
<dd>
Takes an integer and outputs as many &quot;hello world!&quot;s
</dd>
</dl></div>
</div>
<small>Generated: 2013-12-21 11:45:52 UTC</small>
</div>
</body>
</html>

View file

@ -204,6 +204,18 @@ proc Exec(cmd: string) =
echo(cmd) echo(cmd)
if os.execShellCmd(cmd) != 0: quit("external program failed") if os.execShellCmd(cmd) != 0: quit("external program failed")
proc buildDocSamples(c: var TConfigData, destPath: string) =
## Special case documentation sample proc.
##
## The docgen sample needs to be generated twice with different commands, so
## it didn't make much sense to integrate into the existing generic
## documentation builders.
const src = "doc"/"docgen_sample.nim"
Exec("nimrod doc $# -o:$# $#" %
[c.nimrodArgs, destPath / "docgen_sample.html", src])
Exec("nimrod doc2 $# -o:$# $#" %
[c.nimrodArgs, destPath / "docgen_sample2.html", src])
proc buildDoc(c: var TConfigData, destPath: string) = proc buildDoc(c: var TConfigData, destPath: string) =
# call nim for the documentation: # call nim for the documentation:
for d in items(c.doc): for d in items(c.doc):
@ -352,7 +364,9 @@ proc main(c: var TConfigData) =
copyDir("web/assets", "web/upload/assets") copyDir("web/assets", "web/upload/assets")
buildNewsRss(c, "web/upload") buildNewsRss(c, "web/upload")
buildAddDoc(c, "web/upload") buildAddDoc(c, "web/upload")
buildDocSamples(c, "web/upload")
buildDoc(c, "web/upload") buildDoc(c, "web/upload")
buildDocSamples(c, "doc")
buildDoc(c, "doc") buildDoc(c, "doc")
buildPdfDoc(c, "doc") buildPdfDoc(c, "doc")