Swifty powered 🔌Markdown Documentation generator

Overview

License Language Twitter

SkrybaMD 📝

Simple markdown documentation generator, never again -> git conflicts among the team members which are updating documentation at the same time 💥

Motivation to create SkrybaMD

We all know that in big teams we have a lot of agreements, which needs to be stored somewhere (for newcomers and also for current developers), this script will help you to do this, create your SwiftStyleGuide.md, ArchitectureDescription.md etc. documentation in easy to maintain way 🚀

Therefore, creating of documentation for your project, should not limit you at all! Maintaining and editing documentation needs to be easy as it is possible, also we should minimalise situation when multiple team members are manually editing main documentation file, it leads us only towards problems (git conflicts), and in result slow us down 🛩 . This script is intended to be very easy to use and reduce as much as possible git conflicts among the team members interaction with documentation.

  • By separate file for each Table of Content subject, we can organize information in small encapsulated .md files.
  • There will be no longer situation that someone will hesitate to add another subject in the middle of the documentation (due to manual changing numeration of the subject after his insertion), because all subjects iteration are done by the script.
  • You can define as many incision in the file as you want!
  • You can tap into Table of Content subject and you will be redirected to particular place in the documentation file.

How it works?

Features

  • automatic subject enumeration
  • separation of content by using different source .md file for each Section. In this way there will be very small probability to have merge conflicts in the team
  • multiple incisions, you can define easily structure which will support e.g. 1.1.1.3 subject incision
  • Table of Content subject are linked

Usage

  1. Define shape of your documentation

To do so, you need to create your own doc_shape.txt (see and play with Example folder).

Follow convention explained below:

doc_shape.txt example:

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

NOTE You can skip subject content file source name in doc_shape.txt file, in result you will get only subject without content in the output file e.g.:

i || General ||

  1. Create files content for each subject

If in current directory you have not created source .md file for each subject defined in doc_shape.txt, script will do it for you after first run. In the shape example which we see above, it will be e.g. file with the general.md name for "General" subject. Base on mentioned general.md file, script will create documentation body.

  1. Run Script

Base

Run script using terminal in the directory of previously defined files (doc_shape.txt and content subjects .md files).

$ SkrybaMD generate MySuperDocumentation - if you have installed SkrybaMD globally 🌍

or

$ ./SkrybaMD generate MySuperDocumentation - if you have SkrybaMD script in the current directory 🏠

You will find markdown generated MySuperDocumentation.md file in the same directory 💥

Define custom relative path for output file

Skryba by default is taking the same directory for creating output file as doc_shape.txt has, but you can specify your own path for the outpuf using output --path option (see --help for more info).

$ SkrybaMD output --path ./Documentations/MySuperDocumentation

ENJOY 🙌

NOTE: you can play around with script using "Example" folder from this repository

Check help

If you are not sure how to use it, go and hit --help to get verbose instructions

$ SkrybaMD --help

Installation

Using Homebrew

$ brew install robertherdzik/homebrew-SkrybaMD/SkrybaMD

Compiling from source

$ git clone https://github.com/robertherdzik/SkrybaMD.git
$ cd SkrybaMD
$ make install

Contribution

If you have any idea how to improve the project, feel free to do it 🙌 ❤️

You might also like...
Code and documentation for my talk Anime-fy Yourself Using Core ML
Code and documentation for my talk Anime-fy Yourself Using Core ML

Anime-fy Yourself Code and documentation for my talk Anime-fy Yourself Using Core ML Convert from PyTorch to Core ML To convert @bryandlee's PyTorch i

Dash-iOS - Dash gives your iPad and iPhone instant offline access to 200+ API documentation sets

Discontinued Dash for iOS was discontinued. Please check out Dash for macOS instead. Dash for iOS Dash gives your iPad and iPhone instant offline acce

 Sample iOS App  - A collection of examples and patterns for Unit Testing, UI Testing, handling Result/Optionals, writing documentation
 Sample iOS App - A collection of examples and patterns for Unit Testing, UI Testing, handling Result/Optionals, writing documentation

 Sample iOS App - A collection of examples and patterns for Unit Testing, UI Testing, handling Result/Optionals, writing documentation, and more

Extract English from Documentation Comment.

E2DC Extract English text from Swift's Documentation Comment. ドキュメンテーションコメントに書かれた英語を翻訳したい場合に、便利かもしれないツールです。 (現時点では Swift のみ大雑把に対応) 2022-03-29.7.59.48.

Federal Data SDK built in the Swift programming language. Follow the link for the documentation:

Swift-Federal-Data-SDK Federal Data SDK built in the Swift programming language Until the Swift language becomes more stable, consider this a beta rel

Website for AudioKit documentation.
Website for AudioKit documentation.

AudioKit.io audiokit.io hosts DocC documentation for all AudioKit packages. Running the Website The first and only thing we need to do is add a workin

Swifty and modern UserDefaults

Defaults Swifty and modern UserDefaults Store key-value pairs persistently across launches of your app. It uses NSUserDefaults underneath but exposes

The most swifty way to deal with XML data in swift 5.

SwiftyXML SwiftyXML use most swifty way to deal with XML data. Features Infinity subscript dynamicMemberLookup Support (use $ started string to subscr

A sweet and swifty YAML parser built on LibYAML.
A sweet and swifty YAML parser built on LibYAML.

Yams A sweet and swifty YAML parser built on LibYAML. Installation Building Yams requires Xcode 11.x or a Swift 5.1+ toolchain with the Swift Package

Swifty Date & Time API inspired from Java 8 DateTime API.

AnyDate Swifty Date & Time API inspired from Java 8 DateTime API. Background I think that date & time API should be easy and accurate. Previous dates,

A Swifty API for attributed strings

SwiftyAttributes A Swifty API for attributed strings. With SwiftyAttributes, you can create attributed strings like so: let fancyString = "Hello World

Fashion is your helper to share and reuse UI styles in a Swifty way.
Fashion is your helper to share and reuse UI styles in a Swifty way.

Fashion is your helper to share and reuse UI styles in a Swifty way. The main goal is not to style your native apps in CSS, but use a set

Swifty, modern UIAlertController wrapper.
Swifty, modern UIAlertController wrapper.

Alertift Alertift.alert(title: "Alertift", message: "Alertift is swifty, modern, and awesome UIAlertController wrapper.") .action(.default("❤️"))

🍞 Loaf is a Swifty Framework for Easy iOS Toasts
🍞 Loaf is a Swifty Framework for Easy iOS Toasts

Loaf 🍞 Inspired by Android's Toast, Loaf is a Swifty Framework for Easy iOS Toasts Usage From any view controller, a Loaf can be presented by calling

Swifty closures for UIKit and Foundation
Swifty closures for UIKit and Foundation

Closures is an iOS Framework that adds closure handlers to many of the popular UIKit and Foundation classes. Although this framework is a substitute f

A swifty iOS framework that allows developers to create beautiful onboarding experiences.
A swifty iOS framework that allows developers to create beautiful onboarding experiences.

SwiftyOnboard is being sponsored by the following tool; please help to support us by taking a look and signing up to a free trial SwiftyOnboard A simp

Swifty regular expressions

Regex Swifty regular expressions This is a wrapper for NSRegularExpression that makes it more convenient and type-safe to use regular expressions in S

Swifty API for NSTimer

SwiftyTimer Modern Swifty API for NSTimer SwiftyTimer allows you to instantly schedule delays and repeating timers using convenient closure syntax. It

Swifty TVML template manager with or without client-server

TVMLKitchen 😋 🍴 TVMLKitchen helps to manage your TVML with or without additional client-server. Requirements Swift3.0 tvOS 9.0+ Use 0.9.6 for Swift2

Comments
  • Wrong header size

    Wrong header size

    Summary1 has incorrect header size (H4 but should have H3)

    i || General ||
    i || Architecture || architecture_config.md
    ii || Our Approach || our_approach.md
    iii || CI and Rest || ci_and_rest.md
    iiii || Summary || summary.md
    iii || Summary1 || summary.md
    
    bug 
    opened by robertherdzik 1
Releases(0.1.0)
Owner
Robert Herdzik
iOS Developer 🌶
Robert Herdzik
Xcode .appiconset generator for Adobe Illustrator.

Creating AppIcon sets from Adobe Illustrator This repo is rewrited from original repo https://github.com/CaryChamplin/CreatingIconsFromAI. Just genera

gitmerge 73 Nov 9, 2020
AVXCAssets Generator takes path for your assets images and creates appiconset and imageset for you in just one click

AVXCAssets Generator Often while developing an app, We ran into a condition when we need to scale images to each and every aspect ratios for icons and

Angel Vasa 336 Aug 16, 2022
Generate Markdown documentation from source code

SourceDocs SourceDocs is a command line tool that generates markdown documentation files from inline source code comments. Similar to Sphinx or Jazzy,

Eneko Alonso 344 Sep 14, 2022
Generate Markdown documentation from source code

SourceDocs SourceDocs is a command line tool that generates markdown documentation files from inline source code comments. Similar to Sphinx or Jazzy,

Eneko Alonso 344 Sep 14, 2022
docc2html - A static site generator for DocC documentation archives

Tool to convert "DocC" archives, a format to document Swift frameworks and packages: Documenting a Swift Framework or Package, to a static HTML site.

DocZ 103 Sep 2, 2022
Objective-c code Apple style documentation set generator.

About appledoc IMPORTANT NOTICE: collaborators needed appledoc is command line tool that helps Objective-C developers generate Apple-like source code

tomaz 4.2k Sep 16, 2022
A documentation generator for Swift projects

swift-doc A package for generating documentation for Swift projects. Given a directory of Swift files, swift-doc generates HTML or CommonMark (Markdow

SwiftDoc 1.7k Sep 23, 2022
Swift Markdown is a Swift package for parsing, building, editing, and analyzing Markdown documents.

Swift Markdown is a Swift package for parsing, building, editing, and analyzing Markdown documents.

Apple 1.9k Sep 18, 2022
nef💊a toolset to ease the creation of documentation in the form of Xcode Playgrounds

nef, short for Nefertiti, mother of Ankhesenamun, is a toolset to ease the creation of documentation in the form of Xcode Playgrounds. It provides com

Bow 253 Sep 7, 2022
The iOS framework that grows only as fast as its documentation

Nimbus is an iOS framework whose feature set grows only as fast as its documentation. Support status Nimbus is in a supported maintenance mode, meanin

featherless 6.5k Sep 26, 2022