mk-project documentation

mk-project supported languages

mk-project propose you to write simple documentation using simple markup languages:

  • The texinfo syntax.
  • The ReST (ReStructured Text) syntax.
  • The different Markdown dialects available are:
    • Markdown
    • Markdown github
    • Markdown mmd
    • Markdown phpextra
    • Markdown strict

Note

The Markdown language is not standardized inversely to the ReST language.

So it exist different dialects of the Markdown language.

mk-project use some packages to support this languages:

  • The pandoc package.
  • The python(3)-docutils and the rst2pdf packages.
  • The texinfo and texlive packages.

mk-project output formats

So mk-project support many output formats for this simple markup language:

  • HTML.
  • HTML5.
  • pdf (or dvipdf).
  • odt.
  • epub (using the epub3 format).
  • man (Manual pages).
  • info (info pages or books).
  • xml.
  • latex.
  • plain text.

Note

By using the texinfo syntax can have a makeinfo html output by using the HTML output format.

Likewise the divpdf output for texinfo input files.

mk-project input/output files

mk-project documentation is organized into meaningfull folders:

For input files you get a folder for every supported language which contains files clever named (for automatisation).

If your project is named my_project:

$ ls ./doc/md

my_project2epub.md   my_project2latex.md  my_project2plain.md
my_project2html5.md  my_project2man.md    my_project2xml.md
my_project2html.md   my_project2odt.md
my_project2info.md   my_project2pdf.md


$ ls ./doc/rst

my_project2epub.rst   my_project2latex.rst  my_project2plain.rst
my_project2html5.rst  my_project2man.rst    my_project2xml.rst
my_project2html.rst   my_project2odt.rst
my_project2info.rst   my_project2pdf.rst

$ ls ./doc/texinfo

my_project2epub.texi   my_project2latex.texi  my_project2plain.texi
my_project2html5.texi  my_project2man.texi    my_project2xml.texi
my_project2html.texi   my_project2odt.texi    my_project.texi
my_project2info.texi   my_project2pdf.texi

Note

The input files are composed from:

your project name - 2 (meaning conversion: to) - target format - .extension

Simply edit the output format(s) target file(s) and let mk-project do the rest for you.

The output is organized in one folder for every output format:

  • ./doc -> /html
  • ./doc -> /html5
  • ./doc -> /info
  • ./doc -> /latex
  • ./doc -> /man
  • ./doc -> /odt
  • ./doc -> /pdf
  • ./doc -> /text
  • ./doc -> /xml

Warning

Don’t rename the input files otherwise mk-project won’t be able to automate the conversion.

You can rename the output files when the work is really done.

mk-project documentation visualize

mk-project permit you to visualize all the output files in different manners:

mk-project will search severals documentation viewer programs on your installation.

Note

  • The make varibale ${BROWSER} will link to your browser.
  • The make variable ${INFO} will link to the info program.
  • The make variable ${MAN} will link to the man program.
  • The make variable ${EPUB} will link to your epub viewer (fbreader or okular) if available.
  • The make variable ${PDF} will link to your pdf viewer if available.
  • The make variable ${ODT} will link to your odt files viewer if available.
note:If mk-project doesn’t find a binary for viewing a file it will use the xdg-open program.

mk-project documentation target

The mk-project make target are clever named in the same manner as the files.

by typing make help The Makefile will output all available targets according your given settings:

$ make help

[...]

make texi2info   # Make info  doc file from *.texi file.
make texi2html   # Make html  doc file from *.texi file.
make texidvi2pdf # Make pdf   doc file from *.texi file.
make texi2text   # Make text  doc file from *.texi file.
make texi2html5  # Make html5 doc file from *.texi file.
make texi2pdf    # Make pdf   doc file from *.texi file.
make texi2man    # Make man   doc file from *.texi file.
make texi2odt    # Make odt   doc file from *.texi file.
make texi2latex  # Make latex doc file from *.texi file.
make texi2xml    # Make xml   doc file from *.texi file.
make texi2plain  # Make plain doc file from *.texi file.
make texi2epub   # Make epub  doc file from *.texi file.

make rst2html  # Make html  doc file from *.rst file.
make rst2pdf   # Make pdf   doc file from *.rst file.
make rst2man   # Make man   doc file from *.rst file.
make rst2odt   # Make man   doc file from *.rst file.
make rst2xml   # Make xml   doc file from *.rst file.
make rst2latex # Make latex doc file from *.rst file.
make rst2html5 # Make html5 doc file from *.rst file.
make rst2epub  # Make epub  doc file from *.rst file.
make rst2info  # Make info  doc file from *.rst file.
make rst2plain # Make plain doc file from *.rst file.

make md2html   # Make html  doc file from *.md file.
make md2html5  # Make html5 doc file from *.md file.
make md2pdf    # Make pdf   doc file from *.md file.
make md2man    # Make man   doc file from *.md file.
make md2odt    # Make odt   doc file from *.md file.
make md2xml    # Make xml   doc file from *.md file.
make md2latex  # Make latex doc file from *.md file.
make md2epub   # Make epub  doc file from *.md file.
make md2info   # Make info  doc file from *.md file.
make md2plain  # Make plain doc file from *.md file.

[...]

using others documentation tools

If you want to use a documentation tool like sphinx, doxygen or the one you use usually.

Their no problem if this meet the following 2 conditions:

  • The documentation generator you use, make usage of a Makefile (even if it’s optionally, choose it.) to build the documentation.

    warning:If it isn’t the case, all is not lost because you can write a some few make targets to make you the life easier.

  • You must put your hands a little bit in the grease for one time to make you the life easier the next many times...

You have to simply build a slot for your documentation generator into the mk-project Makefile.

Per example I’m using the sphinx documentation generator to write this documentation:

  1. So i make a folder for the sphinx project into the mk-project folder.
  2. And according to my settings sphinx generate a Makefile for building the documentation.
$ mkdir sphinx_doc

$ cd sphinx_doc

$ sphinx-quickstart

[...]

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y

[...]

$ ls sphinx_doc
build  Makefile  source
  1. Build the slot in form of some few targets to add to the main Makefile of mk-project.
################################################################################

# sphinx slot.

.PHONY: sphinx-singlehtml sphinx-html sphinx-htmlhelp sphinx-epub sphinx-info sphinx-man

# sphinx Makefile singlehtml target link.
sphinx-singlehtml:
  cd sphinx_doc ; ${MAKE} singlehtml ;

# sphinx Makefile html target link.
sphinx-html:
  cd sphinx_doc ; ${MAKE} html ;

# sphinx Makefile epub target link.
sphinx-epub:
  cd sphinx_doc ; ${MAKE} epub ;

# sphinx Makefile info target link.
sphinx-info:
  cd sphinx_doc ; ${MAKE} info ;

# sphinx Makefile man target link.
sphinx-man:
  cd sphinx_doc ; ${MAKE} man ;

# sphinx Makefile doctest target link.
sphinx-doctest:
  cd sphinx_doc ; ${MAKE} doctest


# sphinx builded files showing targets.
.PHONY: sphinx-show-singlehtml sphinx-show-html sphinx-show-epub sphinx-show-info sphinx-show-man

sphinx-show-singlehtml:
  cd ./sphinx_doc/build/singlehtml ; ${BROWSER} index.html ;

sphinx-show-html:
  cd ./sphinx_doc/build/html ; ${BROWSER} index.html ;

sphinx-show-epub:
  cd ./sphinx_doc/build/epub  ; ${EPUB} *.epub ;

sphinx-show-info:
  cd ./sphinx_doc/build/texinfo ; ${INFO} -f *.info ;

sphinx-show-man:
  cd ./sphinx_doc/build/man ; ${MAN} -f ${PRGNAME}.${MAN_LEVEL} ;

# sphinx clean target.
sphinx-clean:
  cd sphinx_doc ; cd build ; rm -R * ;

################################################################################

And so by writing this documentation

i alternate this 2 self-made targets

$ make sphinx-html

$ make sphinx-show-html

for writing and reading my documentation.

Into my sidebar terminal window of my I.T.E

editor named it-edit

Final word of mk-project documentation

Note

Think to analyze the possibilities provided by

  • pandoc with his many configuration options.
  • the python(3)-docutils tools (rst2epub, rst2html, rst2info, ...) documentation.
  • The texinfo possibilities, per example the possiblity to read an entire book into your terminal through the makinfo tool and info files.

So all this possiblities combined together in one is the powerful mk-project documentation engine !!!

Or use your favorite documentation generator, as you want.

note:Think to inform the mk-project developers about your slots if you think it’s reliable and reusable for the others.