Hi devs,
A few weeks ago I created this post:
https://dev.to/elcotu/documentation-automation-p8m
After a few weeks, I thought it could be useful to share what I've been trying, exploring and building with the intent of automating some documentation workflow.
At first, I've been learning about markdown as it seemed to be a good language to create the documentation source.
Then discovered the Pandoc tool. It's an open source aimed to translate docs from markdown to several formats (*.docx, *.odt, *.pdf, *.html, *.epub and many more). This was practically all I needed, but, how to implement it?
The tool is suitable for Linux and Windows. I'm a newbie on Linux, I have to confess. But with testing in both OS I soon discovered that you can do a lot more in command line with Linux than with Windows (yes, many will think, "of course").
So I started creating git projects with markdown documents, and trying to automate document generation. Sooner or later, I got to a series of use cases for the automation:
A file for each subfolder: Create a docx file with table of contents from the contents of every file in every subdirectory of the current working directory. This is meant to handle the generation of a collection of how-to files, each with a subfolder of images
Filtered doc: Create a docx file with table of contents from the contents of every file in a directory that contains a given string, and then publishes it in a folder in Dropbox. This is meant to compile a single file with all approved or requesting for approval files
Change control: Traverse a directory. Create a file named cdc.md with each file's commit log. Then create a *.docx file with the contents of the original file and the cdc.md file appended at the end of it. This is meant to create doc files with revision history, for compliance with ISO procedures
And then all the cases could be used with other output formats.
Then I thought and worked on the next step. Basically, publishing the file somewhere. Like a Dropbox, FTP or wherever one can share static content.
This is a repository where I'm compiling some Pandoc samples: Pandoc samples
Have anyone worked with such a tool or these requirements in any way?
Saludos,
Top comments (0)