mk-project documentation¶
Introduction¶
mk-project currently support only one single documentation generator: sphinx.
sphinx was first design to generate official python documentation but time has past and sphinx
has become very popular at first by the python community.
Without any particular extension (like autodoc) sphinx is based on the R.e.S.T Re Structured Text language but Mardown can be used through modifying the conf.py file.
The Rest language is an easy markup language as like markdown but it is standardized (Markdown not) and can be extented what sphinx does.
| note: | Some R.e.S.T Re Structured Text extension permit to build C andf C++ documentation without using any extension. |
|---|
You are a sphinx user:¶
So everything is are right.
You aren’t a sphinx user¶
Let me convince you to adopt sphinx by learning the easy markup R.e.S.T Re Structured Text or Markdown language.
For generating documentation in many formats, mk-project generate make targets from the make output according which sphinx extension are installed on your system.
Per exemple currently on my system.
make sphinx-html # to make standalone HTML files
make sphinx-dirhtml # to make HTML files named index.html in directories
make sphinx-singlehtml # to make a single large HTML file
make sphinx-pickle # to make pickle files
make sphinx-json # to make JSON files
make sphinx-htmlhelp # to make HTML files and an HTML help project
make sphinx-qthelp # to make HTML files and a qthelp project
make sphinx-applehelp # to make an Apple Help Book
make sphinx-devhelp # to make HTML files and a Devhelp project
make sphinx-epub # to make an epub
make sphinx-epub3 # to make an epub3
make sphinx-latex # to make LaTeX files, you can set PAPER=a4 or PAPER=letter
make sphinx-latexpdf # to make LaTeX files and run them through pdflatex
make sphinx-latexpdfja # to make LaTeX files and run them through platex/dvipdfmx
make sphinx-lualatexpdf # to make LaTeX files and run them through lualatex
make sphinx-xelatexpdf # to make LaTeX files and run them through xelatex
make sphinx-text # to make text files
make sphinx-man # to make manual pages
make sphinx-texinfo # to make Texinfo files
make sphinx-info # to make Texinfo files and run them through makeinfo
make sphinx-gettext # to make PO message catalogs
make sphinx-changes # to make an overview of all changed/added/deprecated items
make sphinx-xml # to make Docutils-native XML files
make sphinx-pseudoxml # to make pseudoxml-XML files for display purposes
make sphinx-linkcheck # to check all external links for integrity
make sphinx-doctest # to run all doctests embedded in the documentation (if enabled)
make sphinx-coverage # to run coverage check of the documentation (if enabled)
- Many themes are available.
- Many contrib packages are available for extending sphinx in many ways.
- The rdt theme provide a web service, format the output in his theme and provide the documentation downloadable in many format.
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.
| note: | If mk-project doesn’t find a binary for viewing a file it will use the xdg-open program as fallback. |
|---|
Warning
The sphinx-show-\* targets are set arbitrary
as best as I can
because their is either no way to know into which sub-folder the documentation will be generate
and nor the filename the documentation will have...
Simply trust me or correct it yourself if necessary.
mk-project slots¶
Always remember that you can write some make targets into the mk-project Makefile.
To ease you the documentation generating process and so extend mk-project.
Per example by the first version of mk-project, it use a mix of:
- The
pandocpackage. - The
python(3)-docutilsand therst2pdfpackages. - The
texinfoandtexlivepackages.
To provide ReST, Markdown and texinfo documentation generation but Only one page per output format.
but I used sphinx to write the documentation of the version 1.0 of mk-project
with some few self -builded targets like this:
################################################################################
# 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 * ;
################################################################################
rst2man¶
If you get the program rst2man installed on your system,
mk-project will create a folder named rst2man into the project tree into
which you will find a file ${PRGNAME}.rst to edit a man-page with rst2man.
| warning: | Because the man-page is often apart from the documentation. |
|---|