How can I include script-generated content into documentation built by mkdocs (or mike)?
For example, I'd like to present a table of the command-line arguments of a program, and currently the most complete listing (and descriptions) for those arguments (as supported by a given version of the program) is the output from the program itself (invoked with the --help flag). Similarly as for API documentation, if I was to manually transcribe into a markdown file then there would be a maintenance burden to prevent drift between the docs and codebase. Do I need to pre-orchestrate a script that generates entire markdown files, or is there a way to embed shell commands within the docs source (to be evaluated automatically when the docs are built)?
Related
Since the codebase is quite large, Doxygen takes a really long time to run. If I could obtain the modified files from some version control system and run Doxygen on them, is it possible to merge the existing documentation with the new pages generated?
If so, how can this be done?
Doxygen does not have an incremental build, though there are some mechanisms that do speedup the generation slightly:
Generated images (e.g. call graphs, inheritance graphs are "cached" i.e. in short a md5sum is stored and when this does not change for the graph the image is not regenerated)
for "independent" parts it is possible to create "tag" files (see documentation e.g. TAGFILES)
We want to keep track of changes in a LaTeX document in such a way that people who can't read LaTeX can also see the changes at once. The .tex files are stored in a git repository. So detailed information about the changes is available.
For this purpose I think it might be possible to use the git diff output between two revisions to generate the PDF and somehow mark the changes since the selected other revision of the document.
Do you know of an (easy) way to achieve this?
Do you know of other ways to visualize differences between PDF files?
[Expanding on my comment, since it apparently helped :-) ]
latexdiff is a Perl script that can diff two LaTeX documents and mark up changes without the distractions of the LaTeX markup itself. The README says:
latexdiff is a Perl script, which compares two latex files and marks
up significant differences between them (i.e. a diff for latex files).
Various options are available for visual markup using standard latex
packages such as "color.sty". Changes not directly affecting visible
text, for example in formatting commands, are still marked in
the latex source. Note that only files conforming to latex syntax will
be processed correctly, not generic TeX files. Some further
minor restrictions apply, see documentation.
A rudimentary revision facilility is provided by another Perl script,
latexrevise, which accepts or rejects all changes. Manual
editing of the difference file can be used to override this default
behaviour and accept or reject selected changes only.
The author is F Tilmann.
The project is developed on Github, but you can get the script in a tarball from CTAN if you prefer. The link in the comment is a useful overview of how to use it.
I've a reasonable large C/C++ project and want to generate only a HTML version of the documentation by Doxygen. In my Doxyfile I've written
GENERATE_LATEX = NO
In deed, there is no latex directory in the specified output directory; just html. However, I'm getting output by pdfTex on stderr:
...
This is pdfTeX, Version 3.1415926-1.40.11 (TeX Live 2010)
restricted \write18 enabled.
entering extended mode
(./_formulas.tex
LaTeX2e <2009/09/24>
...
Output written on _formulas.dvi (279 pages, 49376 bytes).
Transcript written on _formulas.log.
...
Why?
Doxygen's installation instructions list LaTeX as an optional (additional) tool, which is not required. Thus I assume, it is not required for basic functionality of HTML generation.
How can I make Doxygen not execute pdfTex? (no, I do not want to uninstall *TeX on my machine)
The file _formulas.tex is created as the result of using formulas.
If you want formulas without the need for LaTeX you can set USE_MATHJAX to YES.
There are several doxygen commands whose purpose is to create links in the documentation (#link, #ref).
I am currently using the #ref command to create a link to a custom file, written in a language not supported by doxygen (xml).
I would like to alter this link so that it points to a precise line in the file.
Is there a doxygen command that allows to do that ?
I'm not sure that \ref or \link can do this. However, if they could, one problem of adopting this approach is that the links will become invalid if you change the contents of the file you are linking to without changing the link. This is one of the problems of separating source code and documentation.
Rather than linking to a particular line in another file why don't you include the particular part of the file you are interested in in the documentation? You could either:
include the whole file with \include (there is also \includelineno) and just reference relevant parts of it in the text (e.g. "function xxx in the code below"), or
include snippets of the file where you need to refer to them in the documentation using \snippet.
Edit: Alternatively, you could use the \dontinclude command which, together with the \line, \skip, \skipline, and \until commands allows you to include specific lines/blocks of a particular file. See the example in the \dontinclude documentation.
There are struct definitions in the .h file that my library creates after I build it.. but I cannot find these in the corresponding .h.in. Can somebody tell me how all this works and where it gets the extra info from?
To be specific: I am building pth, the userspace threading library. It has pth_p.h.in, which doesn't contain the struct definition I am looking for, yet when I build the library, a pth_p.h appears and it has the definition I need.
In fact, I have searched every single file in the library before it is built and cannot find where it is generating the struct definition.
Pth uses GNU Autoconf, Automake, and Libtool. By running ./configure you'll be running a shell script which eventually runs m4 to detect the presence of a whole bunch of different system attributes and make changes to a number of files.
It looks like it boils down to ./configure generating Makefile from Makefile.in and then running something via make that triggers the shtool subcommand scpp:
pth_p.h: $(S)pth_p.h.in
$(SHTOOL) scpp -o pth_p.h -t $(S)pth_p.h.in -Dcpp -Cintern -M '==#==' $(HSRCS)
Obscure link, but here's an shtool-scpp manpage, which describes it as:
This command is an additional ANSI C
source file pre-processor for sharing
cpp(1) code segments, internal
variables and internal functions. The
intention for this comes from writing
libraries in ANSI C. Here a common
shared internal header file is usually
used for sharing information between
the library source files.
The operation is to parse special
constructs in files, generate a few
things out of these constructs and
insert them at position mark in tfile
by writing the output to ofile.
Additionally the files are never
touched or modified. Instead the
constructs are removed later by the
cpp(1) phase of the build process. The
only prerequisite is that every file
has a ``"#include ""ofile"""'' at the
top.
.h.in is probably processed within a configure (generated from configure.ac) script, look out for
AC_CONFIG_FILES([thatfile.h])
It replaces variables of the form #VAR# in the .in file with their values.
Edit: Just noticed if I'm right you should retag your question