Doctor Mark Down

Markdown to Html compiler for creating simple documentation that scales with your project. You can browse this document as part of documentation generated by Doctor Mark Down itself on its GitHub Pages.

Why?

Maintaining documentation is expensive. There are many tools that tries to address this issue out there. Some of them uses different aproaches some of them are pretty similar and differs only in features, API or implementation. Doctor Mark Down is not an alternative to any of these (or at least I do not know any of tool using the same aproach). To be clear there is no one good way to solve every case. You should probably consider if Doctor Mark Down fits your needs before you use it in your project. The reason I wrote Doctor Mark Down is that I missed the tool which fits my needs for some of my projects or projects I came across with my coleagues & collaborators. Documentation should be both accesible (think about easy HTML compilation) and easy to maintain (think about keeping it up to date with your project).

How is Doctor Mark Down do NOT Works

The most common solution is generate documentation directly from source files using its comments. This approach has its advantages and disadvantages. The good thing is that documentation lives directly besides source code it refers to. It's easy to track comments updates when implementation changes and also it's supper easy to automate documentation deploy during release etc. Another important thing might be that it's supper easy to access documentation when someone works with source directly. The down side (or at least I think) is that it's really hard to know how actual documentation will look like based on source (comments in source code). Also if you start to adding examples and description in your comments it starts to be quite hard to navigate your actual implementation. Often comments starts to be even larger than actual code which is not cool. I found it's usually hard to keep comments up to date especially when you're spiking some experimental feature. It's also hard to update coments afterwards or decide which part of your code needs to be docummented deeply and which implementation detail doesn't need to be documented at all. Super annoying thing can be when you for some reason need to switch to different tool and realise that structure of your comments is not compatible with new approach (new tool expect different structure). Personally I do not comment my source too much in favour of test/spec suit which descibes API anyway and is proven correct. Anyway still you'll probably need at least some solution for documenting public API especially for libraries.

Another approach I came around few times is to use static site generator like Jekyll. With this kind of tool the documentation written in some nice markup language (like mark down) and using some template for HTML export. This is nice because you don't need to care about some weird parser which comments generator usually uses. Also creating custom templates is supper familiar and documentation can be updated by non-technical people. Anyway you lost some of the great features of comment approach has. For example your documentation no longer lives together with your implementation. Even if they share same repository, usually you need to put all Markdown files in some _posts folder etc. Then you have to think about both structure of your modules and your documentation. It's also harder to keep a track of which part of documetation needs to be updated if some implementation changes. Also links in your documentation does not corespond with structure of your code anymore and you loose the benefit of easy accessibility for developers working with source directly.

How is Doctor Mark Down Works

Doctor Mark Down is not better in any of these categories but it comes with reasonable compromise between both. Its approch is simple. It uses markdown files instead of comments but these files live beside actuall implementation. Routes of generated html reflect structure of fils so links works across local copy, Github and generated HTML. It lets you easily define custom templates using templating language with your custom CSS and JS. It offers out of the box syntax highlighting. It lets you decide what is worth documenting and what not.

Instalation

Doctor Mark Down is written in typescript and available via npm as compilated javascript package.

npm install -g doctor-mark-down

You can also use library level version if you want and use public APIs in your projects:

npm install --save doctor-mark-down

Usage

If you have doctor-mark-down globaly instaled, you should be able to run this command from terminal.

docmd [options]

Options

All options are optional. Anyway you should use them to overwrite default values. Here is list of available options

Name Shortcut Default Description
--recursive -r off Recursive mode
--files -f ["README.md"] List of source files
--skip-first-headline -s false Skip first headline in menu tree (only for non recursive)
--out-folder -o "docs" Compiled files will be stored to this folder
--depth -d 6 Depth limit of navigation tree (only for non recursive)
--template -t default Path to template
--ignore -i node_modules .git documentation, bower_components Ignored directories

For explanation of how recursive and basic mode here You can find complete guide for templating here

State of Art

Please be aware that this package is in state of Experiment/Proof of concept stage. This means API can or can't change heavilly over time. There is no guarantees that this software will hit stable release or will be maintain for long time. If you found this project interesting please consider any contribution to make stable release happen.

Contributing

All sorts of contributions are wellcome. You fork or clone this repository.

Most of the tasks are already automated using npm scripts.

Dependencies

Node.js should be the only requirement. Anyway this was not tested using Windows. If you ran into some troubles feel free to open issue.

Install dependencies

npm install

Running Tests

Jasmine test framework is used. The most important parts are tested. There are still few things that can be test more deeply. Anyway Typescript provides some extra safety over JavaScript so there is not need to write any large integration tests. If you plan to contribute to this repository always think about providing PR with tests case by case. Its usually good to have at least one test per PR if you fixing bug or providing new feature.

npm test

Build project

Source is written in typescript. You can comple javascript running build command as follows:

npm run build

This will egenerate dist folder containing whole project files. This folder is ignored by git. This step is required if you want to execute ./bin/docmd.

DOCMD Doctor Mark Down

You can compile Doctor Mark Down documentation for Doctor markdow itsef. This will build project (same as running npm run build) and use builded bin/docmd for generating documentation:

npm start

Improvements I Can Think of...

MIT License

Copyright (c) 2016 Marek Fajkus

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.