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
- written as easy markdown text
- additional support for javadoc like formatting
- responsive design through templates
- show api and internal developer info with code
- automatic generation helper
To see what it will give you see at this documentation which is completely made with itself.
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.
You find the top bar which contains the alinex core links. The tree of pages on the left with an icon to switch between User API Documentation and Developer Code Documentation.
To navigate within the page you may use the table-of-contents on the top right corner.
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.
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:
sudo npm install -g alinex-codedoc --production
codedoc --helpTo do this you install it into your own module:
# from within your module directory
sudo npm install --save alinex-codedocAlways have a look at the latest changes in the {@link Changelog.md}
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 call and its options.
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.
Resources like images, html or stylesheets will be copied directly to the output folder.
Because you may refer to them directly from your documentation.
Additional resources in other directories not included in code (ignored by above) can be
given as .docresource list.
You have to
- include it into your project (as described above)
- call the {@link setup()} method
- call the {@link run()} method
See the following example using CoffeeScript or JavaScript:
::: detail CoffeeScript
# load modules
codedoc = require 'alinex-codedoc'
config = require 'alinex-config'
# setup the template search paths and config
codedoc.setup (err) -> config.init (err) -> main()
# running the document generation
main = ->
# 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 JavaScript
:::
Find more information about calling the code documentation in the {@link index.coffee}.
Firstly all pages will be found and it's documentation extracted into two versions:
- api documentation only contains documentation code blocks and documentation code not marked as 'internal'
- developer documentation with code
Next the API doc will be parsed and converted to markdown as all other parts of the documentation and put together. In an first attempt it will be converted to html to extract structural information out of it.
Out of the structural information a page tree and symbol lookup table will be build
for optimization. This is used firstly to resolve document tags like @link into markdown.
Additionally automatic code conversion will take place.
In the final step the complete reports are build and written to file with the structural
information for the html page tree.
Also the static files like images... will be copied to the documentation folder. As far as possible these steps are done in parallel.
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 CoffeeScript
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 JavaScript
:::
This allows you to put your templates also under:
- var/src/template/report/...
- var/local/template/report/...
- /etc//template/report/...
- ~/./template/report/...
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:
DEBUG=codedoc codedoc # general steps in document creation
DEBUG=codedoc:parser codedoc # parsing of source files and code tags
DEBUG=codedoc:process codedoc # detailed file processing information
DEBUG=codedoc:doctags codedoc # transforming document wide tags
DEBUG=codedoc:transcode codedoc # transforming code
# look into required modules:
DEBUG=config codedoc # registering paths for template search
DEBUG=report codedoc # conversion into htmlYou can also combine them using comma or use only DEBUG=* to show all.
(C) Copyright 2016-2017 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.