Github project source: LINK.
intro
Let's start first from the point which will clarify whether this blog post is for you, or is a total waste of your precious time, having this established, you can dive deep into it, or go back to your favorite 9gag section ;)
You should spend your time reading this article if:
you want to maintain your documentation in Markdown (.md) format
if you want to have clear process to generate .md documentation
you work in the team (more than one dev which would like to take care of documenting stuff), or you just love to manage your .md document in consistent/ease way
you are tired of manual intended management in your documentation content
many times you were blocked to add some point of your documentation, straight in the middle, due to the necessity to modify manually further sections punctuation in the doc (I have facet this a lot!)
...ok, now we have clear, and you can decide whether to read further or just skip it.
what is SkrybaMD for?
SkrybaMD is a very simple, Swift powered documentation generator. Is fully open source, so you are able to contribute, or post your ideas related to the script there. Look for it here.
is it hard to use it?
Honestly I need to say, that is really straightforward to use!
Steps to follow:
1 . install it using e.g. brew:
$ brew install robertherdzik/homebrew-SkrybaMD/SkrybaMD
Note, that more installation options you can find in the github repo Readme
2 . create shape doc_shape.txt file
3 . in doc_shape.txt create corresponding three structure with your sub document files names, like:
i || General || general.md
i || Architecture || architecture_config.md
ii || Our Approach || our_approach.md
i || CI and Rest || ci_and_rest.md
i || Summary || summary.md
4 . execute in your doc_shape.txt directory $ SkrybaMD MySuperDocumentationFileName terminal command, and you are done!
Skryba will generate, final documentation output file, with consistent look and feel, as well you will get e.g. Table of Content for free there. Now each time you or your team member wants to modify, he needs to only update ‘shape’ file and regenerate documentation using mentioned terminal command.
You can find in here how automatically generated documentation looks like base on the doc_shape.txt file.
NOTE
Additionally you can specify some more parameters once you use SkrybaMD, please check README to see the latest functionalities of the scrypt.
is it hard to get rid of it, once I decide to do so?
The case is that, since as an output, you get a final .md documentation file, you just stop using SkrybaMD, and can go back to manual documentation shaping. So as you can see, this script is totally not addictive at all for your project/workflow.
Original article source LINK
Top comments (0)