I'm trying to include an example in my C ++ documentation through Sphinx, Breathe and Doxygen.
It doesn't seem to be easy, because the #example statement doesn't work.
And with the #include statement, the *.rst-file is output as simple text and not as code.
does anyone have an idea how to do something like that?
Related
I don't know the effect of option dsource of ocamlc.the -h option tell me it's undocumented
I know the use of dparsetree and dtypedtree,it can show me the ast
I try to use the option dsource,to a file test.ml,It seems to return me the source code,without the null line and the comment,and at bottom tell me the waring of the source code.
Is it the effect of option dsource?Thanks!
-dsource pretty-prints the AST using the OCaml syntax after desugarring syntax extensions such as camlp4 and ppx.
It's mostly used to debug ppxs. The content is exactly the same as -dparsetree (except in source form, instead of AST).
I just spent a few minutes grepping the OCaml compiler sources, and here is what I found.
The -dsource command-line flag sets the dump_source field to true in the Clflags module.
This setting in turn causes the compiler to do something like this in driver/compile.ml when compiling an implementation (.ml) file.
if !Clflags.dump_source then
fprintf ppf "%a#." Pprintast.structure ast
In other words, it pretty-prints the code part of the AST in a form that looks like source code.
Things look similar for an interface (.mli) file, except that it prints out the signature rather than the code.
Since OCaml has a rather flexible front-end, I would guess this is helpful to see the final result of any syntactic transformations that have been applied to the code. (But I might be wrong, I'm not an OCaml compiler hacker.)
I suggest you start looking at the code in driver/compile.ml if you want to figure out more.
Is it possible to include a code snippet in the text section like this in Rmarkdown?
Yes it is, just use it the same way.
I'm working on a C++ project and really fell in love with the Sphinx documentation build system. I managed to setup Doxygen and Breathe to produce and provide the C++ descriptions to Sphinx.
I can't figure out how Google's Ceres Solver documentation was done. Their API reference for example contains class names followed by lots of text, sometimes even with code block examples as shown in the previous link. Is there a way to write Doxygen documentation inside the source files and achieve this?
Another example is this class documentation, which has around two pages of text. I somehow doubt that all this text is located in the source files as Doxygen comments. I have the feeling that all the extra text has been written in the restructured text sources for the documentation and nothing in the c++ source files. But then what is the point of using doxygen and breathe...
Or asked differently, where should I put high-level information about the code? I mean I can document class1 and class2 in their sources, but somewhere I need to explain how both of them interact and are used together. This is what the documentation of the Ceres Solver does so nicely in my opinion.
Alternatively you could point me to a C++ project with the Sphinx + Doxygen + Breathe pipeline and open source documentation. Then I can see for myself how to do these things. Unfortunately I don't know about any project.
I missed the github link for the Ceres Solver. There the sources of the documentation can be found. I'm a bit disappointed, because the complete documentation is written in the Restructured Text source files and NOT inside the c++ code. Basically they reference the class name with .. class:: className and then add ReST markdown for informative text, example code blocks etc. One example is given in "Modeling Non-linear Least Squares"
I'm using the listings package in LaTeX to include source code, but some of my source code runs off to the right and so some lines are obviously too long. Does anyone know if there is a way to mark the margin when I'm writing the code, perhaps depending on the \setlength parameters I set in my LaTeX environment so that I know to stop there? I'm using Microsoft Visual C++ 2010 and TeXworks for this particular problem, but I often just use Emacs to write both C++ code and LaTeX.
Here's a snippet from LaTeX I'm using:
\lstdefinestyle{C++}
{float=h!, frame=single, language={[Visual]C++}, numbers=left, numberstyle=\tiny, tabsize=2}
\lstinputlisting[style=C++, label=lst:RANDU, caption=RANDU C++ Implementation]{RANDU.cpp}
Here's a snippet of what the output of this looks like, I'd like to know where to end lines in my IDE so that it doesn't exceed the right border:
Thanks in advance!
You could use packages like fill-column-indicator or column-enforce-mode. Both available also with MELPA.
The downside is that you will need to manually update the number of columns you want when you update your \setlength, unless you write some code to do it for you.
Use: breaklines=true in the options. Example:
\lstdefinestyle{C++}
{
float=h!, frame=single, language={[Visual]C++}, numbers=left, numberstyle=\tiny, tabsize=2, breaklines=true
}
when i read through source files of opensource projects i often come across some weird phrases in the comments
/*
#brief ......
#usage.....
#remarks....
#par....
*/
questions
1.What are they?(were not mentioned when i was learning c++)
2.Do they have any documentation(where)
They are just comments and as such have no special meaning in C++. They are probably to allow a documentation generator (For example Doxygen) to extract the data from the comments.
Those are for some flavour of automatic documentation generator. Another program runs through the code looking for comments of like you see there. The #... keywords identify how the documentation should be laid out, and that program generates pretty HTML or printed documentation directly from the source code. It's a way to keep the docs up-to-date with the code more easily.