This is part of the Sphinx document I'm trying to generate a PDF for:
Overview
--------
Use this `Cookiecutter <https://cookiecutter.readthedocs.io>`_ template to generate
an empty Python package. Features include:
* Boilerplate tests and documentation
* `Python setup configuration`_
* Open source software license
* Code style checking via `pre-commit`_
* `GitLab CI/CD integration`_
* `Editorconfig`_
* Miscellaneous files, such as `Changelog`_
* A `README`_
.. _Python setup configuration: {{cookiecutter.project_slug}}/setup.py
.. _pre-commit: {{cookiecutter.project_slug}}/.pre-commit-config.yaml
.. _GitLab CI/CD integration: {{cookiecutter.project_slug}}/.gitlab-ci.yml
.. _Editorconfig: {{cookiecutter.project_slug}}/.editorconfig
.. _Changelog: {{cookiecutter.project_slug}}/CHANGELOG.rst
.. _README: {{cookiecutter.project_slug}}/README.rst
I'm using make latexpdf. This generally works correctly, except for this bit. I can't get LaTeX to cooperate with these Cookiecutter links, though it looks fine in HTML. I've tried formatting the links in various ways in Sphinx, but it always ends up generating the same LaTeX, which generates the following error:
! Extra }, or forgotten \endgroup.
<recently read> }
l.129 ...}\}/setup.py}{Python setup configuration}
^^M
The generated LaTeX itself contains:
126:
127: \item {}
128: \sphinxAtStartPar
129: \sphinxhref{\{\{cookiecutter.project\_slug\}\}/setup.py}{Python setup configuration}
130:
I admittedly don't know much about LaTeX, but this line looks fine to me. It seems to escape all the { and } that it should, and open and close the rest properly?
Related
The video tutorial in http://www.kframework.org/index.php/Lesson_4,_LAMBDA:_Generating_Documentation;_Latex_Attributes suggests that we should use kompile lambda --pdf, but when I run it I got the following error:
[Error] Critical: Unknown option: --pdf (Unknown option: --pdf)
The kdoc --help option also result in a Command 'kdoc' not found error.
How do I correctly use this option to generate the formatted K definition?
The kdoc functionality (and --pdf) has not worked for quite some time.
If you want LaTeX ASTs output for given individual terms, you can use --output latex for any of kast, krun, or kprove. Unfortunately this does not work for entire definitions yet, and will not auto-format for you (it only outputs an AST, you'll still need to tell LaTeX how to render the nodes in said AST).
I have a latex file which needed to include snippets of Lua code (for display, not execution), so I used the minted package. It requires latex to be run with the latex -shell-escape flag.
I am trying to upload a PDF submission to arXiv. The site requires these to be submitted as .tex, .sty and .bbl, which they will automatically compile to PDF from latex. When I tried to submit to arXiv, I learned that there was no way for them to activate the -shell-escape flag.
So I was wondering if any of you knew a way to highlight Lua code in latex without the -shell-escape flag. I tried the listings package, but I can't get it to work for Lua on my Ubuntu computer.
You can set whichever style you want inline using listings. It's predefined Lua language has all the keywords and associated styles identified, so you can just change it to suit your needs:
\documentclass{article}
\usepackage{listings,xcolor}
\lstdefinestyle{lua}{
language=[5.1]Lua,
basicstyle=\ttfamily,
keywordstyle=\color{magenta},
stringstyle=\color{blue},
commentstyle=\color{black!50}
}
\begin{document}
\begin{lstlisting}[style=lua]
-- defines a factorial function
function fact (n)
if n == 0 then
return 1
else
return n * fact(n-1)
end
end
print("enter a number:")
a = io.read("*number") -- read a number
print(fact(a))
\end{lstlisting}
\end{document}
Okay so lhf found a good solution by suggesting the GNU source-hightlight package. I basically took out each snippet of lua code from the latex file, put it into an appropriately named [snippet].lua file and ran the following on it to generate a [snippet]-lua.tex :
source-highlight -s lua -f latex -i [snippet].lua -o [snippet]-lua.tex
And then I included each such file into the main latex file using :
\input{[snippet]-lua}
The result really isn't as nice as that of the minted package, but I am tired of trying to convince the arXiv admin to support minted...
I'm working on the documentation of a component using Doxygen and I want to include UMLdiagrams in between the text.
I know how to do most of it, as I simply need to copy the .tuml source into my .dox file and run doxygen. However, one of my diagrams is a class diagram that includes other .iuml files, like explained in the PlantUML site.
So, basically, I do:
#mainpage main_page MyDoxygen
\
...
\
#startuml
\
!include iuml_files/Class01.iuml
!include iuml_files/Class02.iuml
\
MainClass <|-- Class01
MainClass <|-- Class02
\
#enduml
Long story short, I don't know how to make Doxygen understand it must look for the .iuml files in the directory (relative path) I'm giving as argument to the include directive.
If I wasn't clear enough as to what I need, please let me know and I will try make it clearer.
Can I please get some help?
I had a similar problem (I own the Word Add-in for plantuml)
You can specify the java property "plantuml.include.path" in the command line :
java -Dplantuml.include.path="c:/mydir" -jar plantuml.jar atest1.txt
(see http://plantuml.sourceforge.net/preprocessing.html)
I expect it'll work when you modify the batch file for calling Plantuml
http://plantuml.sourceforge.net/doxygen.html
I had a similar request for my Word Addin for Plantuml and here it worked.
The Real Answer
Use the PLANTUML_INCLUDE_PATH = ./someRelativeDir configuration, visible in the Doxygen wizard's DOT panel.
The include path is relative to your Doxygen config, ie the starting directory from which the doxygen config is taken.
A Red Herring
I'm leaving the rest of this answer here in case anyone found it previously.
I wrongly reported a bug because I needed new reading glasses and didn't notice a stray character in my path.
This was resolved as not a Doxygen bug
For any interested parties, this is what I saw.
Running PlantUML on generated file /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/inline_umlgraph_1.pu
Preprocessor Error: Cannot include /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/handDrawnStyle.iuml
Error line 2 in file: /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/inline_umlgraph_1.pu
Some diagram description contains errors
error: Problems running PlantUML. Verify that the command 'java -jar "/Library/Java/Extensions/plantuml.jar" -h' works from the command line. Exit code: 1
This is using the configuration setting
PLANTUML_INCLUDE_PATH = ./iumltToCopy
Sharper eyes than mine (at the time) noticed the extra character in the path iuml t ToCopy
I have a git repo project in eclipse which I have been documenting using doxygen (v1.8.4).
If I run the latex make ion a fresh clone of the project it runs fine and the PDF is made.
However, if I then run a doxy build, which completes OK, then attempt to run the latex make, it fails for
! Package inputenc Error: Keyboard character used is undefined
(inputenc) in inputencoding `utf8'.
See the inputenc package documentation for explanation.
Type H <return> for immediate help.
...
I have tried switching the encoding of the doxyfile by setting DOXYFILE_ENCODING to ISO-8859-1 with no change in the result... How can I fix this?? Thanks.
EDIT: I have used no non-UTF-8 chars as far as I know in my files, the file referenced before the error is very short and definitely doesn't have non-UTF-8 chars in it. I've even tried clearing my latex output dir and building from scratch with no luck...
EDIT: Irealised that the doxy build only appears to run correctly. It doesnt show any errors, but it should, for example run DOT and build about 10 graphs. The console output says Running dot, but it doesn't say generating graph (n/x) like it should when it actually makes the graphs...
Short answer: So by a slow process of elimination I found that this was caused by a single apostrophe in a file that had appeared to be already built and made without error!!
Long answer: Firstly I used used the project properties to flip the encoding from the default Cp1252 to UTF-8. Then I started removing files one-by-one until rebuilding and remaking after each removal, until the make ran successfully. I re-added all files, but deleted the content in the most recently removed file and tested the make - to confirm it was this file and only this file that caused the issue. the make ran fine. So I pasted the content back into the empty file, and started deleting smaller and smaller sections of the file, again rebuilding and remaking each time until I was left with a good make without the apostrophe and a bad one with it... I simply retyped the apostrophe (as this would then force it to be a UTF-8 char) and success!! Such an annoying bug!
Dude you made it a hard way. Why not use python to do the work for you:
f = open(fn,"rb")
data = f.read()
f.close()
for i in range(len(data)):
ch = data[i]
if(ch > 0x7F): # non ASCII character
print("char: %c, idx: %d, file: %s"%(ch,i,fn))
str2 = str(data[i-30:i+30])#.decode("utf-8")
print("txt: %s" % (str2))
I am trying to use some Doxygen filter for Visual Basic in Windows.
I started with Vsevolod Kukol filter, based on gawk.
There are not so many directions.
So I started using his own commented VB code VB6Module.bas and, by means of his vbfilter.awk, I issued:
gawk -f vbfilter.awk VB6Module.bas
This outputs a C-like code on stdin. Therefore I redirected it to a file with:
gawk -f vbfilter.awk VB6Module.bas>awkout.txt
I created this Doxygen test.cfg file:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = awkout.txt
QUIET = NO
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
To produce the documentation I issued:
doxygen test.cfg
Doxygen complains as the "name 'VB6Module.bas' supplied as the second argument in the \file statement is not an input file." I removed the comment #file VB6Module.bas from awkout.txt. The warning stopped, but in both cases the documentation produced was just a single page with the project name.
I tried also the alternative filter by Basti Grembowietz in Python vbfilter.py. Again without documentation, again producing errors and without any useful output.
After trials and errors I solved the problem.
I was unable to convert a .bas file in a format such that I can pass it to Doxygen as input.
Anyway, following #doxygen user suggestions, I was able to create a Doxygen config file such that it can interpret the .bas file comments properly.
Given the file VB6Module.bas (by the Doxygen-VB-Filter author, Vsevolod Kukol), commented with Doxygen style adapted for Visual Basic, I wrote the Doxygen config file, test.cfg, as follows:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = readme.md VB6Module.bas
QUIET = YES
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
FILTER_PATTERNS = "*.bas=vbfilter.bat"
where:
readme.md is any Markdown file that can used as the main documentation page.
vbfilter.bat contains:
#echo off
gawk.exe -f vbfilter.awk "%1%"
vbfilter.awk by the filter author is assumed to be in the same folder as the input files to be documented and obviously gawk should be in the path.
Running:
doxygen test.cfg
everything is smooth, apart two apparently innocuous warnings:
gawk: vbfilter.awk:528: warning: escape sequence `\[' treated as plain `['
gawk: vbfilter.awk:528: warning: escape sequence `\]' treated as plain `]'
Now test\html\index.html contains the proper documentation as extracted by the ".bas" and the Markdown files.
Alright I did some work:
You can download this .zip file. It contains:
MakeDoxy.bas The macro that makes it all happen
makedoxy.cmd A shell script that will be executed by MakeDoxy
configuration Folder that contains doxygen and gawk binaries which are needed to create the doxygen documentation as well as some additional filtering files which were already used by the OP.
source Folder that contains example source code for doxygen
How To Use:
Note: I tested it with Excel 2010
Extract VBADoxy.zip somehwere (referenced as <root> from now on)
Import MakeDoxy.bas into your VBA project. You can also import the files from source or use your own doxygen-documented VBA code files but you'll need at least one documented file in the same VBA project.
Add "Microsoft Visual Basic for Applications Extensibility 5.3" or higher to your VBA Project References (did not test it with lower versions). It's needed for the export-part (VBProject, VBComponent).
Run macro MakeDoxy
What is going to happen:
You will be asked for the <root> folder.
You will be asked if you want to delete <root>\source afterwards It is okay to delete those files. They will not be removed from your VBA Project.
MakeDoxy will export all .bas, cls and .frm files to location:<root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
cmd.exewill be commanded to run makedoxy.cmd and delete <root>\source if you've chosen that way which alltogether will result in your desired documentation.
A logfile MakeDoxy.bas.logwill be re-created each time MakeDoxy is executed.
You can play with configuration\vbdoxy.cfg a little if you want to change doxygens behavior.
There is still some room for improvements but I guess this is something one can work with.