By Peter Antoine
Copyright (c) 2011-2012 Peter Antoine
Released under the Artistic Licence
I need a tool to be able to write documentation that stays in step with the code. But, I want to documentation to have the format of a document and not be decided by the code. Also I want to be able to generate diagrams (state machines and sequence diagrams) from within the code, without have weird markup in the comments (like dot code).
Also, I want the documentation to be decided by the build system so that it can be reshaped to match the delivery build configuration.
This document generation system is built in the style that the code is built. That is a compile and a link. This means that the documentation can be generated by rules in the makefile in the same way that the code is, so that different documentation is built using the same rules and is different depending on the build.
The final documentation will be built using a real document that will reference the generated model to build the final documentation. This also means that the same data can be placed within the document as many times as required. Also, the document does not have any "noise" in it that is not there by choice.
The input format of the docs will be based on MarkDown. This is a because MarkDown is simple to use and they are many tools that can convert this into any document style. The format of Markdown is obviously slightly different from all the others. It is based on the traditional markdown, but also pulls in the tables styles.
It has been implemented as mentioned above as a three commands, the compiler (psdc) and the linker (psdl) that generates the model and a final linker (pdp) that will generate the documentation for the supported file formats.
The documentation is produced by the compiler collecting all the atoms from the source file, and generating an object file. The linker then gathers the selected object files and builds a model file. This file then gets passed into the document generator that is then used to build the documents for the formats that are required.
Currently, the compiler does not include a pre-processor or depend on the C/C++ one. If required it can always be called and have the result passed into the compiler.
The current specification is where you can look for what is currently supported Spec. To see how to use it, it is best to look at the test files as (ironically) the documentation for the system is not complete yet.
For how to use the functions look in the tests as this is a make system that will build the files in the source directory.
But the simple quick start is:
For the source files: pdsc -o test_file_one.c.pdso test_file_one.c pdsc -o test_file_two.c.pdso test_file_two.c pdsc -o test_file_three.c.pdso test_file_three.c pdsc -o test_file_four.c.pdso test_file_four.c pdsc -o test_file.h.pdso test_file_one.h
To link the above:
pdsl test_file_one.c.pdso test_file_two.c.pdso test_file_three.c.pdso \
test_file_four.c.pdso test_file.h.pdso -o test.gout
And finally to produce the documentation: pdp -itest.gout -d output test_markdown.md -f text,html,manpage
And in the output directory you will have the text,html and manpage formatted output.
What's left to do?
The functions are now at a beta level, and it produces final documentation. There are probably a shed load of bugs in it, and these will be worked out.
A current major failing of the system, is that the compiler uses a hand rolled parser that is hard wired to the model generator. This was because the original idea was for a lightweight processor to produce simple diagrams, but the features that this system now supports have grown. So the parser needs to be replaced with a yacc based one, and the model generation code needs to be more generic so it will be easier to extend the supported types. The input parser model is going to be a plugin like the output so a large portion of the pdsl function will be re-written to make it easier to support more languages.
The system does not support windows (fully). But it should and will.
The current output formats that are currently supported in manpage, text, html. (La)TeX will be added to this list of supported formats.
Also, need to extend it for different languages, especially looking at VHDL as the auto generation of state machines would be of really great use there.
The code 'section' text is not run through the Markdown parser, but this will be fixed.
Add some (more) Pandoc extensions that I like and I think works with auto-generated documentation. The "Title Block" being the most important, followed by multi-lined tables. Which mostly been left because of time to get the Beta version out, and get some other eyes on the system before it goes to far.
Finally (and ironically) it needs to be documented. The documentation is weak and will be updated, the excuse is I had to build the tool before using it? Some of the documentation on the source is for older iterations of the system, and in one place for the next iteration. This will be fixed, look at the test files for now, and all will be fixed soon.
Enjoy, the stupidity of the above.
16th September 2012