This project requires JVM version of at least 1.7
Table of Contents top
- Table of Contents
- documentr
- IMPORTANT
- Overview
- Getting Started
- Building the Package
- Logging - slf4j
- Artefact Publishing - Github
- Artefact Publishing - Bintray
- Artefact Publishing - gradle plugin portal
- All-In-One
- License
documentr top
documentation (README) generator for projects in both markdown and asciidoc - this utilises the templar templating language - including generation of table of contents
IMPORTANT top
Staring at version 2, the build.gradle
task configuration has changed, from documentrSetting
to just plain documentr
NEW top
documentr {
directory = '../some/directory/'
verbose = 'false'
extension = 'md' // this is the default
// extension = 'adoc' // perhaps you want asciidoc?
documentrFile = 'documentr.json' // perhaps you want to use a different JSON file?
}
OLD top
documentrSetting {
directory = '../some/directory/'
verbose = 'false'
extension = 'md' // this is the default
// extension = 'adoc' // perhaps you want asciidoc?
documentrFile = 'documentr.json' // perhaps you want to use a different JSON file?
}
ERRORS Running documentr
top
If you get an error along the following lines:
* What went wrong:
Execution failed for task ':documentr'.
> 14961 > 664
This may intermittently occur if you run it in --daemon
mode as the documentr process alters files on the filesystem which are cached.
You will need to run this without the --daemon
flag.
Overview top
Why document anything? top
Ever duckduckgo, google, bing or yahoo searched for an answer to your question? You are searching the world's largest index of documentation - all of which was written by somebody else (or maybe you)
Whilst documentation is seen as the thing that developers love to read, but hate to write, documentation for any project/module/framework/extension helps:
- Increase adoption - that's right, if you want people to use your project, documentation makes is so much easier
- You to understand your code better - if you can explain it in clear English (or whatever your language of preference is), then it is probably well-thought out code. Furthermore, when documenting, you will inevitably come across things that would be good to add to the code-base
- Give an all-round happy feeling - and we all like this, don't we!
Do's and Don'ts of documentation top
- Give a quick example of how to get up and running
- Provide a cut and paste-able example (including import statements if applicable) - This is what your users will do
- Provide examples for integration points with other libraries - not everybody knows how to use a technology that you have chosen
- Keep it up to date - old, out of date documentation is almost as bad as no documentation
- Make it as easy as possible to get your software up and running as quickly as possible
- Tell people to read the test cases
- People want to use your software, not understand your how you test your code
- Yes, your audience is technical - but you are probably mocking so many things that they will have to delve through so many test cases just to find the one that they want - just to get up and running
- If you are using a BDD framework like JBehave or Cucumber, then your audience will have to go through so many levels of indirection just to attempt to figure out what to do
- Let your documentation get out of date
The above Do's and Don'ts were the basis for why
documentr
was created, minimising the hand created stuff and maximising the information
For this README
file, the only files that are hand-written are:
src/docs/pre-usage.md
,src/docs/post-usage.md.templar
src/docs/table-of-contents.md
files. All other information is generated from the documentr.json
file in
the root of this project.
Getting Started top
- Create a
documentr.json
file (if one doesn't exist - we will create one automatically for you) - Generate the
README
file either through the gradle plugin, or through the command line - ... There is no step 3
Gradle Plugin tasks top
There are two tasks that come with this plugin (a simple gradle tasks
will list them for you):
Documentation tasks
-------------------
documentr - Generates a README file for your project.
documentrHelp - Documentr - prints out a help message
Step 1 - Create the documentr.json
file top
This is a simple JSON formatted file:
This is a simple JSON file as show below:
{
"context": {
"pluginId": "synapticloop.documentr"
},
"templates": [
{ "type":"inbuilt", "value":"badge-travis-ci" },
{ "type":"inbuilt", "value":"badge-bintray" },
{ "type":"inbuilt", "value":"badge-shield-io-github-release" },
{ "type":"inbuilt", "value":"badge-shield-io-gradle-plugin" },
{ "type":"inbuilt", "value":"jvm-compatability" },
{ "type": "markup", "value": "\\n\\n# Table of Contents\\n\\n" },
{ "type": "toc", "value": "2" },
{ "type": "toclinks", "value": "true" },
{ "type": "tocbacktotop", "value": " <sup><sup>[top](#documentr_top)</sup></sup>"},
{ "type":"inbuilt", "value":"project-name" },
{ "type":"inbuilt", "value":"project-description" },
{ "type":"file", "value":"src/docs/pre-usage.md" },
{ "type": "markup", "value": "### The `documentr.json` file\\n\\n" },
{ "type": "markup", "value": "This is a simple JSON file as show below:\\n\\n" },
{ "type": "markup", "value":"\\n```\\n" },
{ "type": "file", "value":"documentr.json" },
{ "type": "markup", "value":"\\n```\\n" },
{ "type": "markup", "value":"> *in fact - the above file is included from the file system `documentr.json`, so that it is always up-to-date with the correct information...*\\n\\n" },
{ "type":"template", "value":"src/docs/post-usage.md.templar" },
{ "type":"markup", "value":"\\n\\n```\\n" },
{ "type":"file", "value":"src/main/resources/USAGE.txt" },
{ "type":"file", "value":"src/main/resources/HELP.txt" },
{ "type":"markup", "value":"\\n```\\n" },
{ "type": "file", "value":"src/docs/table-of-contents.md" },
{ "type":"inbuilt", "value":"gradle-build" },
{ "type":"inbuilt", "value":"logging-slf4j" },
{ "type":"inbuilt", "value":"publishing-github" },
{ "type":"inbuilt", "value":"publishing-bintray" },
{ "type":"inbuilt", "value":"dependencies" },
{ "type":"inbuilt", "value":"publishing-gradle-plugin" },
{ "type":"inbuilt", "value":"publishing-all-in-one-jar" },
{ "type":"inbuilt", "value":"license-mit" },
{ "type":"inbuilt", "value":"attribution" }
]
}
in fact - the above file is included from the file system
documentr.json
, so that it is always up-to-date with the correct information...
The above file generated this complete README
file, while only requiring 2 files to be created by hand.
Step 2 - Generate the README
file top
Include the plugin and simply run:
gradle documentr
This will also parse the build file and place various objects into the context that are then available to use in the templar templates.
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "gradle.plugin.synapticloop:documentr:2.9.0"
}
}
apply plugin: "synapticloop.documentr"
plugins {
id 'synapticloop.documentr' version '2.9.0'
}
By default the plugin looks for a documentr.json
file in the current directory, you may override this by doing the following:
documentr {
directory = '../some/directory/'
verbose = 'false'
extension = 'md' // this is the default
// extension = 'adoc' // perhaps you want asciidoc?
documentrFile = 'documentr.json' // perhaps you want to use a different JSON file?
}
Note that this will generate the README
file in the same directory (i.e. ../some/directory/README.md
or ../some/directory/README.adoc
)
The verbose
setting will output the pre-parsed and rendered templar template to the console
simply run
java -jar documentr-2.9.0-all.jar
By default this will generate the README
file looking at the current directory for a documentr.json
file.
note that you will need to place everything in the
context
object manually when running from the command line
Running:
java -jar documentr-2.9.0-all.jar --help
Will yield the following information:
Generate a README.md file for projects utilising the 'templar' templating
engine.
Usage:
java -jar documentr-all.jar [OPTIONS}
All OPTIONS are optional
Where OPTIONS are one of
-h, --help will print out a longer version of the usage message.
Note: If you use this parameter all other parameters
are ignored
~ OR ~
-d, --directory <arg> The directory in which the 'documentr.json' file
resides, default the current working directory
(i.e. '.')
-e, --extension <arg> The extension for the README file, default '.md'. Only
'.md' and '.adoc' are supported by the inbuilt
templates, only other extension __MUST__ not use the
'inbuilt' template type
-v, --verbose <arg> Output more verbose information
This will look for a documentr.json file in the directory, parse it, collate
the associated resources and generate the documentation.
The format of the documentr.json file is as follows:
{
"context": {
"key": "value",
"key2": "value2",
...
},
"templates": [
{ "type": "template-type", "value": "template-name" },
{ "type": "template-type", "value": "template-name" },
...
]
}
The "context" keyed object is a JSONObject of key value pairs, and can be any
valid JSON values apart from a JSONArray or another JSONObject (i.e., long,
boolean, string, int).
The "templates" keyed array is a JSONArray of JSONObjects. Each of the
JSONObjects, __MUST__ have a key of "type" and "value". The "type" can only
be one of the following:
- template - this is a 'templar' formatted template that will be used and
parsed - the value is a path to a file
- templar - inline templar format tokens - a useful debugging one is:
{dumpcontext} - which dumps all available context key/value pairs to
the output
- file - the file will be included as is with no parsing done on it
- markup - any valid markdown, with '\\n' being replaced with a new line
character. No templar parsing is done on this.
- markdown - an alias for markup
- inbuilt - one of the in-built templates (see below for a list of the
inbuilt templates).
- toc - build up a table of contents, the value set the level of headers that
will be out put. e.g.: value="1" only h1, value="2" only h1 and h2.
- toclinks - whether to display the table of contents as links, and insert
links into the headers (default false)
- tocbacktotop - this will generate a back to top link for each of the
headers (e.g. h1, h2, h3 etc), the value is the text link (default
'top')
The list of inbuilt templates:
- attribution - a nice attribution to synapticloop for generating this
README file.
- badge-bintray - generation of a bintray download badge with version number
- badge-shield-io-github-release - generation of a github release version
number
- badge-shield-io-gradle-plugin - generation of a gradle plugin version release
number
- badge-travis-ci - build status from travis-ci
- dependencies - Listing out all of the dependencies for the project
- dumpcontext - for debugging, this will dump the available context items to
the output
- gradle-build - gradle build instructions
- gradle-plugin-usage - print out the default gradle plugin usage instructions
- gradle-test - gradle test instructions
- jvm-compatability - Output a JVM compatability notice
- license-apache-2.0 - the standard Apache 2.0 license
- license-bsd-2-clause - the BSD 2 Clause license
- license-bsd-3-clause - the BSD 3 Clause license
- license-mit - the standard MIT license
- logging-slf4j - informing users that slf4j is being used within the project
and information on how to set up various other loggers to utilise it
- project-description - the description of the project
- project-name - the name of the project as an h1 markdown
- publishing-all-in-one-jar - where an artefact is generated with all
dependencies contained within the jar
- publishing-bintray - Information about the publishing of artefacts to the
jcenter bintray repository
- publishing-github - Information about the publishing of artefacts to the
github releases page
- publishing-gradle-plugin - Information about the publishing of artefacts to
the gradle plugins repository
- publishing-jitpack - Information about the publishing of artefacts to the
jitpack repository
- publishing-maven - Information about the publishing of artefacts to the
maven central repository
- test-warn - warning about running tests, which may consume resources, which
may lead to a cost
Generating the table of contents top
documentr
can automatically generate the table of contents for your documentation,
simply by entering the following line into you documentr.json
file:
{ "type": "markup", "value": "\\\\n\\\\n# Table of Contents\\\\n\\\\n" },
{ "type": "toc", "value": "2" },
{ "type": "toclinks", "value": "true" },
{ "type": "toplink", "value": " <a name=\\"documentr_top\\"></a>" },
{ "type": "tocbacktotop", "value": " <sup><sup>[top](#documentr_top)</sup></sup>" },
By default, no title is generated - you will need to include one as simple markup.
This will generate the table of contents, and depending on any options, will generate links to the headers, and/or 'back to top links'.
The { "type": "toc", "value": "2" }
line will generate header links up to h2
elements (i.e. both h1 and h2).
If the value
attribute is omitted, then the default is to generate a table of
contents for headers up to level h6
.
This is the anchor name to go back to the top of the README file (rather than
the top of the page. By default this is always set to <a name=\\"#documentr_top\\"></a>
if you wish to change the tocbacktotop
, then you will need to change this as
well.
This is a post processing command and will generate links to the headers in the
page. This option is only invoked if there is a table of contents generated
(i.e. . { "type": "toc", "value": "2" }
)
This is a post processing command and will generate 'back to top' links for all of the included headers.
The line: { "type": "tocbacktotop", value: " <sup><sup>[top](#documentr_top)</sup></sup>"}
will generate a link after every heading (up to the table of content level number
set above).
The value is the HTML/Markdown that is appended to the heading.
If you change the anchor link from #documentr_top
, you MUST also include and
update the toplink
entry above.
Unfortunately the developer of the markdown processor that is in use, does not distinguish block quote level elements correctly such that anything that looks like a header included in a blockquote will also be incorrectly identified as a header. However,
documentr
will attempt to pre-process the code fence blocks and remove them before parsing.
Building the Package top
*NIX/Mac OS X top
From the root of the project, simply run
./gradlew build
Windows top
./gradlew.bat build
This will compile and assemble the artefacts into the build/libs/
directory.
Note that this may also run tests (if applicable see the Testing notes)
Logging - slf4j top
slf4j is the logging framework used for this project. In order to set up a logging framework with this project, sample configurations are below:
Log4j top
You will need to include dependencies for this - note that the versions may need to be updated.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j-impl</artifactId>
<version>2.5</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.5</version>
<scope>runtime</scope>
</dependency>
dependencies {
...
runtime(group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.5', ext: 'jar')
runtime(group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.5', ext: 'jar')
...
}
dependencies {
...
runtime 'org.apache.logging.log4j:log4j-slf4j-impl:2.5'
runtime 'org.apache.logging.log4j:log4j-core:2.5'
...
}
A sample log4j2.xml
is below:
<Configuration status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
</Appenders>
<Loggers>
<Root level="trace">
<AppenderRef ref="Console"/>
</Root>
</Loggers>
</Configuration>
Artefact Publishing - Github top
This project publishes artefacts to GitHub
Note that the latest version can be found https://github.com/synapticloop/documentr/releases
As such, this is not a repository, but a location to download files from.
Artefact Publishing - Bintray top
This project publishes artefacts to bintray
Note that the latest version can be found https://bintray.com/synapticloop/maven/documentr/view
maven setup top
this comes from the jcenter bintray, to set up your repository:
<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation='http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd' xmlns='http://maven.apache.org/SETTINGS/1.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
<profiles>
<profile>
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>central</id>
<name>bintray</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>central</id>
<name>bintray-plugins</name>
<url>http://jcenter.bintray.com</url>
</pluginRepository>
</pluginRepositories>
<id>bintray</id>
</profile>
</profiles>
<activeProfiles>
<activeProfile>bintray</activeProfile>
</activeProfiles>
</settings>
gradle setup top
Repository
repositories {
maven {
url "http://jcenter.bintray.com"
}
}
or just
repositories {
jcenter()
}
Dependencies - Gradle top
dependencies {
runtime(group: 'synapticloop', name: 'documentr', version: '2.9.0', ext: 'jar')
compile(group: 'synapticloop', name: 'documentr', version: '2.9.0', ext: 'jar')
}
or, more simply for versions of gradle greater than 2.1
dependencies {
runtime 'synapticloop:documentr:2.9.0'
compile 'synapticloop:documentr:2.9.0'
}
Dependencies - Maven top
<dependency>
<groupId>synapticloop</groupId>
<artifactId>documentr</artifactId>
<version>2.9.0</version>
<type>jar</type>
</dependency>
Dependencies - Downloads top
You will also need to download the following dependencies:
synapticloop:simpleusage:1.1.2
: (It may be available on one of: bintray mvn central)synapticloop:simplelogger:1.1.1
: (It may be available on one of: bintray mvn central)synapticloop:templar:1.4.1
: (It may be available on one of: bintray mvn central)commons-io:commons-io:2.5
: (It may be available on one of: bintray mvn central)org.json:json:20160810
: (It may be available on one of: bintray mvn central)commons-cli:commons-cli:1.3.1
: (It may be available on one of: bintray mvn central)nl.jworks.markdown_to_asciidoc:markdown_to_asciidoc:1.0
: (It may be available on one of: bintray mvn central)org.pegdown:pegdown:1.6.0
: (It may be available on one of: bintray mvn central)
synapticloop:simpleusage:1.1.2
: (It may be available on one of: bintray mvn central)synapticloop:simplelogger:1.1.1
: (It may be available on one of: bintray mvn central)synapticloop:templar:1.4.1
: (It may be available on one of: bintray mvn central)commons-io:commons-io:2.5
: (It may be available on one of: bintray mvn central)org.json:json:20160810
: (It may be available on one of: bintray mvn central)commons-cli:commons-cli:1.3.1
: (It may be available on one of: bintray mvn central)nl.jworks.markdown_to_asciidoc:markdown_to_asciidoc:1.0
: (It may be available on one of: bintray mvn central)org.pegdown:pegdown:1.6.0
: (It may be available on one of: bintray mvn central)
NOTE: You may need to download any dependencies of the above dependencies in turn (i.e. the transitive dependencies)
Artefact Publishing - gradle plugin portal top
This project publishes artefacts to the gradle plugin portal
Note that the latest version can be found https://plugins.gradle.org/plugin/synapticloop.documentr
All-In-One top
This project's artefact output is an 'all in one' jar which includes all runtime dependencies.
This should appear in the artefact repository along with the compiled code, as a convention, this is usually appended with an -all
classifier
For example:
documentr-2.9.0.jar -> documentr-2.9.0-all.jar
License top
The MIT License (MIT)
Copyright (c) 2017 synapticloop
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
--
This README.md file was hand-crafted with care utilising synapticloop
templar
->
documentr
--