docgen-tool 2.1.3 → 3.0.1

package/source/user-guide/index.txt

@@ -1,245 +0,0 @@
-<style>
-#dg-content, #dg-innerContent {
-  padding-top: 0;
-}
-#banner, #banner-buttons {
-  margin: 0;
-}
-
-#banner {
-  color: #385691;
-  font-weight: bold;
-  padding-top: 30px;
-  background-color: #f7f7f7;
-  box-shadow: inset 0px 5px 5px 0px #e7e7e7;
-}
-
-#banner img {
-  padding: 25px 0 25px 0;
-}
-
-#banner-buttons {
-  background-color: #f7f7f7;
-  padding: 20px 0 20px 0;
-  background-color: #999;
-}
-
-.spaced {
-  margin-right: 15px;
-}
-
-.heading-text {
-  font-size: 16px;
-  text-align: center;
-}
-
-.segment {
-  border-bottom: 2px solid #4d4d4d;
-  padding: 20px 0 20px 0;
-}
-
-.how-it-works li {
-  vertical-align: top;
-  display: inline-block;
-  width: 290px;
-  margin: 10px;
-  padding: 0;
-  border: 2px solid #4d4d4d;
-  border-radius: 10px 10px 0 0;
-}
-
-.how-it-works li p:first-of-type {
-  margin: 0;
-  border: none;
-  background-color: #4d4d4d;
-  color: white;
-  padding: 18px 10px 18px 10px;
-  text-align: center;
-  font-style: italic;
-  font-weight: bold;
-  border-radius: 7px 7px 0 0;
-}
-
-.how-it-works li p:first-of-type a {
-  color: white;
-}
-
-.how-it-works li p:last-of-type {
-  padding:0;
-  margin:0;
-  height: 400px;
-  background-repeat:no-repeat;
-}
-
-.features {
-  margin: 0;
-  padding: 0;
-  width: 100%;
-}
-
-.features li {
-  vertical-align: top;
-  display: inline-block;
-  width: 220px;
-  margin: 10px;
-}
-
-.features li span {
-  vertical-align: middle;
-  margin-right: 5px;
-}
-
-.features li p:first-of-type {
-  margin: 0;
-  padding: 0 0 3px 0;
-  font-size: 14px;
-  font-weight: bold;
-  color: #385691;
-  border: none;
-}
-
-.features li p:last-of-type {
-  padding-top: 5px;
-  margin: 0;
-}
-
-</style>
-
-<div id="banner" class="segment"><div class="w-fixed-width">
-  <p class="w-massive w-center w-no-underline">Better documentation for software products.</p>
-  <img class="w-center" src="files/images/overview.png"  alt="overview" />
-</div></div>
- 
-<div id="banner-buttons" class="segment"><div class="w-fixed-width">
-  <span class="w-center">
-  <a href="https://github.com/mtmacdonald/docgen/releases" class="w-button-link w-colored w-large spaced">Download</a>
-  <a href="https://github.com/mtmacdonald/docgen/issues" class="w-button-link w-dark">Report Issues</a>
-  </span>
-</div></div>
-
-<div class="segment" style="border-bottom: none; margin-bottom:0; padding-bottom:0;"><div class="w-fixed-width">
-<p class="heading-text">
- <strong>DocGen</strong> is a <strong>static website generator</strong> that's ideal for making technical user guides for software products.
-</p>
-
-<h2 class="dg-hiddenTitle" id="features">Features</h2>
-<ul class="features">
-<li>
-  <p><span class="w-icon" data-name="monitor"></span><span>Self-contained website</span></p>
-  <p>Creates a static website that works on any server, or as local files (CD, shared drive etc).</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="document"></span><span>Optional PDF</span></p>
-  <p>Also publishes the website content as a single PDF, using <a href="http://wkhtmltopdf.org">wkhtmltopdf</a>.</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="edit"></span><span>Human-friendly input</span></p>
-  <p>Write in plain text, or the human-friendly <a href="http://commonmark.org">CommonMark</a> format 
-  (Markdown).</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="gear_a"></span><span>Easy to version control</span></p>
-  <p>Easily version control software documentation in sync with its product.</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="clipboard"></span><span>Table of contents</span></p>
-  <p>Automatically creates tables of contents, with links and PDF page numbers.</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="code"></span><span>Code syntax highlighting</span></p>
-  <p>Automatically highlights code blocks, using <a href="https://highlightjs.org">Highlight.js</a>, with language detection.</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="compose"></span><span>Mathematical expressions</span></p>
-  <p>Displays mathematical expressions without plugins, using either
-  <a href="http://khan.github.io/KaTeX/">KaTeX</a> or
-  <a href="https://www.mathjax.org">MathJax</a>.</p>
-</li>
-<li>
-  <p><span class="w-icon" data-name="star"></span><span>Branding and metadata</span></p>
-  <p>Easily brand with a logo, attribute ownership, and attach release notes.</p>
-</li>
-</ul>
-
-<p class="heading-text">DocGen makes it easy for anyone to create high-quality technical documentation.</p>
-
-</div></div>
-
-<div style="padding-top:20px;"><div class="w-fixed-width">
-
-<p class="dg-forceBreak"></p>
-<h2>How it works</h2>
-
-<ul class="how-it-works" id="how-it-works">
-<li>
-  <p>"You write in plain text or human-friendly <a href="http://commonmark.org">CommonMark</a>"</p>
-  <p style="background-image:url('files/images/text.png');"></p>
-</li>
-<li>
-  <p>"DocGen styles and publishes all your content as a website"</p>
-  <p style="background-image:url('files/images/web.png');"></p>
-</li>
-<li>
-  <p>"DocGen also creates an equivalent PDF copy"</p>
-  <p style="background-image:url('files/images/pdf.png');"></p>
-</li>
-</ul>
-
-<table style="width:600px; border:none; padding:0;">
- <tr style="border:none; padding:0;">
- 
-  <td style="border:none; text-align:left; padding:0; vertical-align: top;"><ul>
-   <li class="list-heading">Flexible Input Formats</li>
-   <li>Plain text</li>
-   <li>CommonMark (Markdown)</li>
-   <li>HTML</li>
-   <li>LaTeX mathematical expressions</li>
-   <li>Image diagrams</li>
-   <li>Attach other documents</li>
-  </ul></td>
-  
-  <td style="border:none; text-align:left; padding:0; vertical-align: top;"><ul>
-   <li class="list-heading">Configurable Metadata</li>
-   <li>Branding (logo, title, organization)</li>
-   <li>License, copyright, and legal markings</li>
-   <li>Ownership and attribution</li>
-   <li>Version information</li>
-   <li>Release notes (change log)</li>
-  </ul></td>
-  
- </tr>
-</table>
-
-<blockquote>
-DocGen is probably not the right tool for precision PDF layout. Or for product configurators which need to output 
-variants based on a common template. Docgen is intended more for free-form, human generated content which is regularly 
-updated and refactored, and standardised for each product release.
-</blockquote>
-
-<h2 id="browser-support">Browser support</h2>
-
-Output created by DocGen works in modern browsers (desktop and mobile devices).
-
-<ul><li/>tested in <a href= "http://windows.microsoft.com/en-us/internet-explorer/download-ie">Internet Explorer 9+</a>, 
-<a href= "http://www.google.com/chrome">Chrome</a>, 
-<a href= "https://www.mozilla.org/en-US/firefox/new">Firefox</a>, 
-<a href= "https://www.apple.com/safari">Safari</a></li></ul>
-
-<h2 id="quick-start">Quick start</h2>
-
-<ul>
- <li class="list-heading">In just three commands:</li>
- <li>Install DocGen</li>
- <li>Scaffold an empty template</li>
- <li>Generate a static website</li>
-</ul 
-
-<p>Enter these commands in the terminal:</p>
-
-<pre><code>sudo npm install -g docgen-tool
-docgen scaffold
-docgen run -o $HOME/docgen-example</code></pre>
-
-<p>See the <a href="installation.html">installation guide</a> for more detailed instructions.</p>
-
-</div></div>

package/source/user-guide/installation.txt

@@ -1,49 +0,0 @@
-This section explains how to install DocGen.
-
-Supported platform
-------------------
-
-*'Supported platform'* means the software required to **run** the DocGen tool. The static website **produced** by 
-DocGen will work on all modern browsers on all all major operating systems 
-(see [browser support](index.html#browser-support)).
-
-<p class="w-information">
-	The supported platform for this version of DocGen is: 
-	<strong>Ubuntu 14.04</strong> with <strong>Node.js 0.12.0</strong> 
-	and <strong>wkhtmltopdf 0.12.2.1 </strong>(with patched qt).
-</p>
-
-While other operating systems and dependency versions may work, they are not tested or officially supported.
-
-Dependencies
-------------
-
-DocGen requires **[Node.js](https://nodejs.org)**. To install on Ubuntu Linux, enter these terminal commands:
-
-	curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
-	sudo apt-get install -y nodejs
-
-This method uses the 
-[NodeSource Linux Repositories](https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories)
-(recommended).
-
-For other platforms (not supported), see the [download page](https://nodejs.org/download) or vendor instructions.
-
-Optional dependencies (only for PDF)
-------------------------------------
-
-For optional PDF support, DocGen requires **[wkhtmltopdf](http://wkhtmltopdf.org)**. See the wkthmltopdf website for
-installation instructions.
-
-Quick install with NPM
-----------------------
-
-The quickest way to install DocGen is with **[npm](https://www.npmjs.com)** (the JavaScript package manager). Enter 
-these terminal commands:
-
-	sudo npm install -g docgen-tool
-
-Install by direct download
---------------------------
-
-DocGen can also be installed by [direct download](https://github.com/mtmacdonald/docgen).

package/source/user-guide/parameters.json

@@ -1,37 +0,0 @@
-{
-	"title" : "DocGen - a documentation tool",
-	"name": "DocGen",
-	"version" : "2.1.3",
-	"date" : "29/05/2015",
-	"organization" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"author" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"owner" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"contributors" : [
-		{
-			"name" : "",
-			"url" : ""
-		}
-	],
-	"website" : {
-		"name" : "Github",
-		"url" : "https://github.com/mtmacdonald/docgen"
-	},
-	"backlink" : {
-		"name" : "",
-		"url" : ""
-	},
-	"module" : "",
-	"id" : "",
-	"summary" : "DocGen is a command-line documentation tool for software products. It takes plain text or CommonMark (Markdown) as input, and generates both a static website and a PDF copy.",
-	"marking" : "MIT License.",
-	"legalese" : ""
-}

package/source/user-guide/release-notes.txt

@@ -1,64 +0,0 @@
-DocGen 2.1.3 released 29/05/2015
---------------------------------
-
-- Allow more protocols in CommonMark links (see markdown-it [ticket #108](https://github.com/markdown-it/markdown-it/issues/108))
-
-DocGen 2.1.2 released 28/05/2015
---------------------------------
-
-- Fixed a regression defect (exception when running docgen scaffold) that first appeared in DocGen 2.1.0
-
-DocGen 2.1.1 released 28/05/2015
---------------------------------
-
-- Upgraded all node dependencies to the latest versions
-- Upgraded styles to the latest release of Webknife (1.4.0)
-
-DocGen 2.1.0 released 27/05/2015
---------------------------------
-
-- Added a command-line option for specifying a custom path to wkhtmltopdf
-
-DocGen 2.0.1 released 31/03/2015
---------------------------------
-
-- Fixed the node package and user guide for installing with npm install -g
-
-DocGen 2.0.0 released 31/03/2015
---------------------------------
-
-- DocGen is now open source
-- Rewritten in JavaScript for Node.js
-- Much easier to install (hosted on npm)
-- Dependencies are now version controlled (using npm)
-- Modernized visual style (uses Webknife CSS framework)
-- Input metadata files are now in JSON rather than YAML format
-- Top-level page headings are now inserted automatically (from contents.json)
-- The web and PDF tables of contents both correspond to contents.json
-- Command-line options are now used for configuration, rather than a config file
-- Command-line output is now color coded (green success, red error)
-- Added usage information to the command line interface
-- Generating the PDF is now an optional feature
-- Upgraded to the latest version of the PDF generator (wkhtmltopdf)
-- Added support for mathematical expressions (with KaTex or MathJax)
-- Added support for a list of document contributors (for multiple authors)
-- Added support for a header link back to the application (integrated docs)
-- Added time to the generation timestamp
-- Renamed 'change log' to 'release notes'
-- Fixed issues with fonts and text kerning in the PDF copy
-- Fixed defect where unexpected text appeared on some pages with a page table of contents
-- Dropped support for Internet Explorer 7 and 8
-- Dropped formal support for tool to run on multiple operating systems
-- Removed support for 'Mark of the Web'
-
-DocGen 1.0.1 released 18/01/2012
---------------------------------
-
-- Fixed a bug causing the table of contents headings to sometimes appear in the wrong order
-
-DocGen 1.0.0 released 04/11/2011
---------------------------------
-
-- Ruby implementation (not released as open source)
-- Creates a static website from Markdown input files
-- Also creates a PDF copy using wkhtmltopdf

package/source/user-guide/running.txt

@@ -1,47 +0,0 @@
-Overview
---------
-
-DocGen is a command-line tool which takes plain text input files and outputs a static website.
-
-Command-line usage
-------------------
-
-The DocGen command-line interface includes usage help for both the tool and its subcommands:
-
-	docgen --help
-	docgen run --help
-
-Scaffold command
-----------------
-
-The **scaffold** command creates an *example* input directory. It outputs the minumum files required by DocGen, which 
-can then be used as a template for making any new website.
-
-**Create a scaffold template in the working directory** (./)**:**
-
-	docgen scaffold
-
-**Create a scaffold template in a specified directory:**
-
-	docgen scaffold -o $HOME/docgen-example
-
-Run command
------------
-
-The **run** command transforms an input directory (plain text source) into an output directory (HTML+PDF).
-
-**Basic usage:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output
-
-**Optionally create a PDF:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -p
-
-**Optionally create a redirect page:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -r
-
-> The optional redirect page is an 'index.html' file that is placed in the output's parent directory. The redirect page
-redirects the user to the homepage in the output directory. This is mostly useful for hosting the website without having
-to place all the files in the root directory.

package/source/user-guide/troubleshooting.txt

@@ -1,32 +0,0 @@
-This section gives help on solving common issues with DocGen.
-
-Displaying detailed errors
---------------------------
-
-Pass the **-v** (verbose) option when running DocGen to get more detailed error messages.
-
-PDF missing content
--------------------
-
-In complex pages, the PDF generator (wkhtmltopdf) needs to be given enough time for dynamic content to be rendered. 
-Pass the **-d [milliseconds]** option to increase the rendering time for each page, if required.
-
-Attached files not in PDF
--------------------------
-
-Attached files are not converted to PDF, only the web content is.
-
-Corrupted text characters
--------------------------
-
-Make sure all the input text files are saved with UTF-8 encoding.
-
-Missing logo
-------------
-
-The logo must be PNG format and saved with the path *files/images/logo.png*. 
-
-Other issues
-------------
-
-For any other problems, please submit a [an issue ticket](https://github.com/mtmacdonald/docgen/issues).

package/source/user-guide/upgrading.txt

@@ -1,25 +0,0 @@
-This section explains how to upgrade from old versions of DocGen.
-
-DocGen 1.0.* to DocGen 2.0.0
-----------------------------
-
-DocGen 2 is not backwards compatible with DocGen 1, but the upgrade is easy with these instructions:
-
-- Install DocGen 2 by following the [installation guide](installation.html)
-- Create a replacement 'source' directory, e.g: **<code>docgen scaffold -o $HOME/source</code>**
-- Migrate the source files
-	- Copy the source (.txt) files from the old 'Src' directory to the new 'source' directory
-	- Remove the top-level page headings in each source file (DocGen now inserts these automatically, based on contents.json)
-	- Rename *'change-log.txt'* to *'release-notes.txt'*
-- Migrate the attached content
-	- Place a logo with filename 'logo.png' in 'files/images' directory (the logo is now part of the source)
-	- Copy the images from *'Images'* to *'files/images'*
-	- Copy attached files from *'Files'* to *'files'*
-- Migrate the metadata
-	- Edit *'parameters.json'* with the relevant values from *'doc-parameters.yml'*
-	- Edit *'contents.json'* with the relevant values from *'table-of-contents.yml'*
-- Run DocGen: **<code>docgen -i $HOME/source -o $HOME/output</code>**
-- Check the styling in the latest version still works well with the old content
-- Note that the PDF is no longer generated by default (pass the *'-p'* option)
-
-> DocGen 1 tool-behaviours.yml has been replaced by command-line options. For help, see **<code>docgen run -h</code>**.

package/source/user-guide/version-control.txt

@@ -1,13 +0,0 @@
-One of the benefits of using DocGen for product software documentation is that its plain text source files are easy to 
-version control in sync with the product.
-
-Recommended practice
---------------------
-
-It is recommended to store the documentation **source files** (DocGen input directory) in the same version control 
-repository as the product code. This allows each release of the product to have a matching version of its
-documentation.
-
-> It is not necessary to version control the DocGen output, because this can always be regenerated. If the DocGen
-output is version controlled, file renames, additions, and deletions have to be performed manually in the 
-version control tool.