New documentation process

Generated with the application
Added by David Demelier over 5 years ago

New documentation

The current documentation is on the wiki.

This offers the following benefits:

  • Instant fixes, improvements
  • Easy access and well integration with other redmine stuff

But it also has very awful drawbacks:

  • Changes in the API are painful to mark
  • Offline reading is not possible
  • Adding new functions must be done as quickly as possible

New model

At the very beginning, irccd's documentation was written with AsciiDoc and LDoc. This was nice but also very limited. By the way, it was very difficult to make homogeneous style. AsciiDoc templates and CSS were very hard to edit and LDoc was broken at each update.

I'm currently experimenting the very great tool pandoc, it can converts many formats but the most popular one within pandoc is markdown.

The idea is to document each Lua API function, each irccd event and all books with CMake + pandoc chained.

The major benefits by using pandoc are:

  • Templating very flexible
  • Multiple output formats (HTML, PDF)
  • Markdown editing

So we will be able to publish all irccd documentation to its official page and that will be very well integrated (I hope).

I'm currently porting all API functions and testing it locally. Stay tuned.