documentationtex-general
Is there Documentation Generator for LaTeX like Javadoc for Java or Doxygen for C++?
Especially when defining macros or environments for LaTeX-files throughout a big project it would be useful for the team to have a nice documentation at best auto generated from commentary in the LaTeX-file.
I now compiled such a document listing all internal macros of LaTeX2e which are also useful for package authors. The work title is "List of internal LaTeX2e Macros useful to Package Authors" and I'm planning to release it on CTAN 'soon' (e.g. as 'macros2e') when its out of the beta stage.
The beta release can be found on my website. There is also a feedback form and email address on the website. Please do not hesitate to suggest more macros I might have overlooked, better explanations of already listed macro, report errors of any kind or anything else.
It is now on CTAN. The source repository is public. Please feel free to provide comments, patches or open an issue ticket if you find anything which can be improved.
Documenting LaTeX sources with the default classes and packages is a bit of a patchwork, as the overall system has four major dependencies doc, docstrip, ltxdoc and article, plus the additional commands that you add in the driver.
Some of the major package authors have put a lot of effort to modify the standard classes the same way we all modify the preambles of the standard classes in our documents. Document classes, packages or extensive modifications that stand out are those of the listings (lstdoc), microtype (docstyle) and biblatex (ltxdockit) packages. For the commonly used classes you can have a look at Koma and memoir dtx files. The LaTeX3 project has also an experimental documentation class (l3doc.dtx), which is aesthetically very pleasing.
But in the end, you will probably want to define your own. This is not as hard as it sounds. The major issues in the typography of the documentation part normally lie within the "user manual" section. The implementation section is best done in a less colorful way with the only major change, the graying of the numbering.
Have a look at the microtype and LaTeX3 documentation to see how this improves the looks of the code part, especially when the line numbering gets into the thousands.
Now for the user manual part. This is where you need to put effort and anything is possible, down to having micro typography. A number of improvements are possible here. First to get in some form of boxing and to have a method for pretty printing of LaTeX code using listings. In addition depending on the package or class you are developing, running the actual examples automatically can make life easier. A package I would recommend to add is tcolorbox. It provides environments for display boxes, automatically executing the LaTeX code and is very good at displaying keys in the pgf style. In a preamble with a combination of all these, I managed to get this type of output:
The major difficulty I had was to get the hyperref, lstdoc and tcolorbox to be in the right order and load options without generating any clashes. This worked nicely:
\usepackage[pdftex,bookmarks,raiselinks,pageanchor,hyperindex,colorlinks]{hyperref}
\usepackage{lstdoc}
\usepackage[listings,theorems,documentation]{tcolorbox}
As simple as this sounds, plus the addition of microtypography and changing fonts to:
\usepackage[charter]{mathdesign}
\def\rmdefault{bch} % not scaled
\def\ttdefault{blg}
had a marked improvement in the document typography.
The rest of the commands about 200 lines were to reformat the headers and sectioning commands. For microtypography I cut and pasted the relevant code from the microtype package.
If your package is smallish a very good short solution is to do the following:
\documentclass{article}
\usepackage{a,b,c,d,e} % as required
\usepackage{filecontents}
\begin{filecontents}{foo.sty}
... Package contents
\end{filecontents*}
\input{foo.sty}
\begin{document}
... User manual
... Code documentation
... \lstinputlisting{foo.sty}
\end{document}
The package is typed within the filecontents environment and saved as foo.sty. You then input it in order to use it. At the main document you just input the code using one of the listings commands of the tcolorbox verbatim input commands. For anything up to a 100-200 code lines this is an excellent method and has the advantage that you are always working though one file. In addition while you developing the package you can test it at the same time while staying within one file. Styling of course will still be your own responsibility, but you will get pretty printing for both the manual as well as the code.
I have some code that I am busy with, if you interested to have a copy just post a comment (it is rather lengthy and I will clean it up and post it on github for you during the weekend). However MWE can be found at Different approach to literate programming for LaTeX.
Best Answer
The LaTeX Project have developed a series of tools to help documenting (La)TeX code: this is hardly surprising given the fact hat LaTeX itself is a large and complex piece of software. The combination of various pieces of the 'jigsaw' leads to a file format known as
.dtx('documented (La)TeX source' or something like that). This format combines the ability to extract code from the source using DocStrip with mark-up tools for creating documentation using thedocpackage. I've written about the format before and provided a starting point for creating an 'all in one'.dtx. A minimal-ise version might look something likewhere I've not provided the
.insfile necessary to extract the code from the source, just the necessary set up to typeset some comments.This format is used a lot by LaTeX package authors, so there are many variations on the standard set up on CTAN.