A general code documentation tool
npm install alinex-codedocAlinex CodeDoc: Readme
=================================================
A general code documentation tool based on the concepts of
docco or docker.js.
This tool should help you create browsable documentation out of the comments written
in the code. It is a way between hand written documentation, structured api information
and code highlighting. Read my own thoughts below to know why it is like it is.
The main features are:
- useable for any language
- with easy markdown text
- powerful options like graphs
- additional support for javadoc like formatting
- responsive design through templates
To see what it will give you is shown here in this documentation
which is completely made with it.
::: info Demo / Examples
As an example of the two modes (public/internal view) you can check this documentation
in both forms:
- public -
for all using the module on command line or through the API
- internal -
for developers which want to change this module (to extend or fix it)
:::
> It is one of the modules of the Alinex Namespace
> following the code standards defined in the General Docs.
__Read the complete documentation under
https://alinex.github.io/node-codedoc.__
Philosophy
-------------------------------------------------
How important is documentation? How should it be structured? How to write it? This
all depends on who will write it and mostly who should use it.
In my projects I can answer the last statement easily because I write it and I will
use it and some other guys may be using my modules. After getting that clear I saw that
mostly I have to decide how it should be.
Someone said good code didn't need any documentation but I disagree and will say
documentation may be extended with good code. I don't want to repeat to much information
already in the code. The documentation should also concentrate on the things the
user needs and don't mix internal developer API for mostly external users.
Good examples are very useful because developers will often look at them
and search the details in the text arround afterwards.
With all these thoughts I created this tool as in between of the existing tools.
The documentation should be easy to write and be right beside the code (it may get
not updated if I have to do it in a separate file). I decided to use markdown
as documentation format and write extra files meant to explain how things go
in general. But if it goes deeper and alongside the code I put the markdown just
above the code in comment blocks.
To get a consistent API display for all methods and functions I allow to use JsDoc
tags for API and add some autodetected information from code analyzation.
This all have to be transformed to be displayed in a modern web interface viewable
on any device and searchable (at least through google).
As I sometimes also read documentation about the internal structure and API I added
another mode called code view which is designed for the internal module developer.
To decide which documentation element belongs to the internal developer and which
to the general documentation I used different comment blocks in each language.
I also mixed the docco/docker.js concept of doc + code for the internal documentation.
Workflow
-------------------------------------------------
$$$ plantuml {.right}
interface "CodeDoc" as CLI
folder "Input Directory" as Source {
[Markdown]
[CODE]
[resources]
}
node Analyze
CLI -> Analyze
Markdown -> Analyze
CODE -> Analyze
[languages] ..> Analyze
package Data {
[pages]
[report]
[symbols]
}
Analyze ..> pages
Analyze -> report
Analyze ..> symbols
node Transform
[template] ..> Transform
pages ..> Transform
report -> Transform
symbols ..> Transform
folder "Output Directory" as Doc {
[index] ..> [html]
[other] <.. [html]
}
Transform -> index
Transform -> html
node Copy
resources -> Copy
Copy -> other
skinparam node {
backgroundColor peachpuff
}
$$$
Which files to use firstly depends on the selection of the input folder and the
filter conditions. These filter conditions can be set indirectly using the .docignore
or .gitignore files or be given in the API.
All files matching this conditions will be analyzed. Depending if you generate the normal
view or the developer view document elements are extracted. Therefore the predefined
language syntax is used. If some document parts are found
a report will be generated containing the documentation in markdown format and the page list
and symbols table are filled up, too.
The transformation will use the user definable template to make html reports.
A table of contents will be build out of the pages list and inline @link tags
will be replaced using the symbol table if possible. An index will also be created
redirecting to the first page of documentation. Each html page will be standalone
with all neccessary javascript, css and svg included. Only resources which are
coming through the template (some CDN resources in the default) and the images
you added as relative links are linked.
Resources like images, html or stylesheets will be copied directly to the output folder.
Because you may refer to them directly from your documentation.
Install
-------------------------------------------------
> See the {@link Changelog.md} for a list of changes in recent versions.
You may use it from the command line as CLI Tool or call it directly through the
API from your nodeJS code.
Install the package globally using npm:
`` sh`
sudo npm install -g alinex-codedoc --production
codedoc --help
To do this you install it into your own module:
` sh`from within your module directory
sudo npm install --save alinex-codedoc
Always have a look at the latest changes in the {@link Changelog.md}
Usage
-------------------------------------------------
After global installation you may directly call codedoc from anywhere to work
in the current or defined directory.
See the {@link codedoc.1.md} for explanation of the command line use
and options.
You have to
1. include it into your project
2. call the setup method
3. call the {@link run()} method
See the following example using CoffeeScript or JavaScript:
::: detail {size=max}
` coffee`
codedoc = require 'alinex-codedoc'setup the template search paths
codedoc.setup (err) ->
# do something on error like exit or reporting
if err
console.error err.message
process.exit 1
# run documentation generation
codedoc.run
input: argv.input
find:
exclude: list
output: argv.output
style: argv.style
code: argv.code
, (err) ->
if err
console.error err.message
process.exit 16
console.log 'Documents created.'
:::
::: detail
` coffee2js`
:::
Find more information about calling the code documentation in the {@link index.coffee}.
If you want to use your own style templates within your app's config directory
and you're already using {@link alinex-config} you only have to register the
template type on it by putting the following on top:
::: detail
` coffee`
config = require 'alinex-config'set module search path
(with paths for calling in the upper directory)
config.register 'codedoc', __dirname,
folder: 'template'
type: 'template'
:::
::: detail
` js`
config = require('alinex-config');
// set module search path
// (with paths for calling in the upper directory)
config.register('codedoc', __dirname, {
folder: 'template',
type: 'template'
});
:::
This allows you to put your templates also under:
- var/src/template/report/...
- var/local/template/report/...
- /etc/
- ~/.
Debugging
-------------------------------------------------
If you have any problems you may debug the code with the predefined flags. It uses
the {@link debug} module to let you define what to debug.
Call it with the DEBUG environment variable set to the types you want to debug.
The most valueable flags will be:
` sh`
DEBUG=codedoc* codedoc # more information what goes on
DEBUG=config* codedoc # registering paths for template search
DEBUG=report* codedoc # conversion into html
You can also combine them using comma or use only DEBUG=*` to show all.
License
-------------------------------------------------
(C) Copyright 2016 Alexander Schilling
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
>
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.