I am documenting a group of classes that work together using Doxygen and I wrote an example spread across multiple source files (All referenced from EXAMPLE_PATH). More precisely, I wrote the following:
/*************************************//**
* Some context...
* #example Source1.cpp
*
* More context...
* #example Source2.cpp
****************************************/
The problem is that the output is spread in half in the Example page generated by Doxygen (a page for Source1, another for Source2). I would like it to be all on the same HTML page, with the context and example code together as one tutorial:
Some context...
|----------------------------------------------|
| int main() |
| { |
| //... |
| } |
|----------------------------------------------|
More context...
|----------------------------------------------|
| bool fct() |
| { |
| //... |
| } |
|----------------------------------------------|
Is there a way to accomplish this? I am using Doxygen 1.8.11.
Regards
I found a semi-legit solution: if you add the #example tag at the beginning and use #includes afterwards, it works:
/*************************************//**
* #example "My tutorial"
*
* Some context...
* #include Source1.cpp
*
* More context...
* #include Source2.cpp
****************************************/
However, looking at the error output from Doxygen I get the following message: warning: included file My is not found. Check your EXAMPLE_PATH
The solution is not clean, but is usable for the time being. If you have a better suggestion (i.e. warning removed), please share it and I will accept it.
Related
I have a large c++ project documented with doxygen. I want to use breathe to make nicer manuals. The in-source documentation often contain tables such as this:
/**
* #var somevar
* #brief some variable
* #defgroup somegroup Some Group
* #details This stores some value in some variable
* | English | German | Parameters |
* |---------|--------|------------|
* | `content of somevar %%s in english.\n` | `content of somevar %%s in German\n` |`<Battery percent>` |
*/
I generate the xml docs in build/xml with doxygen and run sphinx to generate the docs.
doxygen Doxyfile
make html
make latexpdf
The directory structure looks like this:
├── build
├── Doxyfile
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── somegroup.rst
├── _static
└── _templates
All works fine, documents are created, but the table is missing. I can see the table in the build/xml/group___somegroup.xml. The table is also shown in the html output of doxygen. But it is missing in the html and pdf generated by sphinx + breathe.
I cannot find any reference that doxygen tables are not supported by breathe. What am I missing?
exhale has some useful info:
Tables
Tip
Everything from here on may cause issues with Doxygen. Use the \rst verbatim environment described in the Doxygen Aliases section.
Use grid tables!!!
The will guide you to their doxygen aliases:
ALIASES
In particular, the two aliases Exhale provides come from Breathe, and allow you to wield full-blown reStructuredText (including directives, grid tables, and more) in a “verbatim” environment. The aliases as sent to Doxygen:
# Allow for rst directives and advanced functions e.g. grid tables
ALIASES = "rst=\verbatim embed:rst:leading-asterisk"
ALIASES += "endrst=\endverbatim"
This allows you to do something like this in your code:
/**
* \file
*
* \brief This file does not even exist in the real world.
*
* \rst
* There is a :math:`N^2` environment for reStructuredText!
*
* +-------------------+-------------------+
* | Grid Tables | Are Beautiful |
* +===================+===================+
* | Easy to read | In code and docs |
* +-------------------+-------------------+
* | Exceptionally flexible and powerful |
* +-------+-------+-------+-------+-------+
* | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 |
* +-------+-------+-------+-------+-------+
*
* \endrst
*/
Not so nice, but I can live with that.
#user1283043 shared a good answer, but it's incomplete if you need to both generate output via Sphinx (where the answer works) and directly from Doxygen (where it doesn't). The solution I came up with involves the use of Doxygen #if statements to conditionally compile two versions of the same table.
For the Doxyfile used to generate the Sphinx output, include the previously mentioned aliases:
ALIASES = "rststar=#verbatim embed:rst:leading-asterisk"
ALIASES += "endrst=#endverbatim"
Then enable a SPHINX section that the Doxygen markup can check for:
ENABLED_SECTIONS = SPHINX
With this in place, you can adjust your Doxygen table markup appropriately:
/**
* #brief Documentation with a table in it
*
* These are the allowed values:
*
* #if SPHINX
* #rststar
* +-------+----------+---------------------------+
* | Value | Range | Description |
* +=======+==========+===========================+
* | FOO | 0..27 | The range for a FOO value |
* +-------+----------+---------------------------+
* | BAR | 91..1372 | The range for a BAR value |
* +-------+----------+---------------------------+
* #endrst
* #else
* Value | Range | Description
* ----- | :------: | -------------------------
* FOO | 0..27 | The range for a FOO value
* BAR | 91..1372 | The range for a BAR value
* #endif
*/
It's a bit ugly and awkward, because you need to enter the same text twice, but you get a proper table both when compiled through Doxygen and when compiled through Sphinx/Breathe.
How can I populate rows in a column with items from the todo lists based on custom sequences?
AKA:
* TODO <<something1>>
* WAITING <<something2>>
* BLOCKED <<something3>>
* TODO <<something4>>
And then a table that I can update using C-c C-c (using something like # TBLFM I'm guessing? ) based on items I add.
| TODO | WAITING | BLOCKED |
| [[something1]] | [[something2]] | [[something3]]|
| [[something4]] | | |
Sounds like a job for kanban: http://draketo.de/light/english/free-software/el-kanban-org-table
I have updated my Sencha CMD version to the lastest version 6, I have seen a new implementation with a new object called "sass" in the app.json and my question is.. How to configure correctly this area? I am working with packages in my app and in this new concept of app.json and newer version of the command line I guess is possible to add a watcher in the different sass folder..
Can you help me with the implementation and correct paths to the packages in the app .json?
Here you can see a first approach:
https://docs.sencha.com/extjs/6.0/whats_new/6.0.0/cmd_upgrade_guide.html
Concretely in the area of the app.json.
Here is what it can look like. You'll have to find the correct pathes for your
packages yourself.
/**
* Comma-separated list of files or folders containing extra Sass. These
* files are automatically included in the Sass compilation. By default this
* is just "etc/all.scss" to allow import directives to control the order
* other files are included.
*
* All "etc" files are included at the top of the Sass compilation in their
* dependency order:
*
* +-------+---------+
* | | base |
* | theme +---------+
* | | derived |
* +-------+---------+
* | packages | (in package dependency order)
* +-----------------+
* | application |
* +-----------------+
*/
"etc": [
"sass/etc/all.scss",
"${toolkit.name}/sass/etc/all.scss",
"../ext/packages/ux/classic/sass/var/layout/ResponsiveColumn.scss"
],
/**
* Comma-separated list of folders containing Sass variable definitions
* files. These file can also define Sass mixins for use by components.
*
* All "var" files are included after "etc" files in the Sass compilation in
* dependency order:
*
* +-------+---------+
* | | base |
* | theme +---------+
* | | derived |
* +-------+---------+
* | packages | (in package dependency order)
* +-----------------+
* | application |
* +-----------------+
*
* The "sass/var/all.scss" file is always included at the start of the var
* block before any files associated with JavaScript classes.
*/
"var": [
"sass/var/all.scss",
"sass/var",
"${toolkit.name}/sass/var"
],
/**
* Comma-separated list of folders containing Sass rule files.
*
* All "src" files are included after "var" files in the Sass compilation in
* dependency order (the same order as "etc"):
*
* +-------+---------+
* | | base |
* | theme +---------+
* | | derived |
* +-------+---------+
* | packages | (in package dependency order)
* +-----------------+
* | application |
* +-----------------+
*/
"src": [
"sass/src",
"${toolkit.name}/sass/src"
]
},
/**
* | A | B |
* | - | - |
* | 123 | This should be a long line with
* a line break without breaking the table |
* | A further | row |
*/
Doxygen stops the table parsing after "with". How can I prevent this behavior?
I found that using markups for table is not convinient enough. if you will switch to html fromat you will not have a problem to break whenever you want.
I have created the following aliases in Doxyfile for my table to simplify the code:
"table_start_b{1}=<table><caption align= bottom>\1</caption>" \
"table_start_t{1}=<table><caption align= top>\1</caption>" \
"table_end=</table>" \
"table_h2{2}=<tr><th>\1</th><th>\2</th></tr>" \
"table_row2{2}=<tr><td align= center>\1</td><td align= center>\2</td></tr>" \
and use it as following :
\table_start_t{Abbreviations}
\table_h2{
Acronym ,
Description }
\table_row2{ "TBD" , "To be
defined" }
\table_end
You have no problem to have a line break in any place.
I'm using the Zend Framework database relationships for a couple of weeks now. My first impression is pretty good, but I do have a question related to inserting related data into multiple tables. For a little test application I've related two tables with each other by using a fuse table.
+---------------+ +---------------+ +---------------+
| Pages | | Fuse | | Prints |
+---------------+ +---------------+ +---------------+
| pageid | | fuseid | | printid |
| page_active | | fuse_page | | print_title |
| page_author | | fuse_print | | print_content |
| page_created | | fuse_locale | | ... |
| ... | | ... | +---------------+
+---------------+ +---------------+
Above is an example of my DB architecture
Now, my problem is how to insert related data to two separate tables and insert the two newly created ID's into the fuse table at the same time. If someone could could maybe explain or give me a topic related tutorial. I would appreciate it!
I assume you got separate models for each table. Then simply insert stuff in Prints table, store returned ID in variable. Then insert stuff in Pages table and store returned ID in another varialble. Eventually insert data in your Fuse table. You do not need any "at the same time" (atomic) operation here. ID of newly inserted rows are returned by save() (I assume you use autoincrement fields for this).
$printsModel = new Application_Model_Prints();
$pagesModel = new Application_Model_Pages();
$fuseModel = new Application_Model_Fuse();
$printData = array('print_title'=>'foo',
...);
$printId = $printsModel->insert( $printData );
$pagesData = array('page_author'=>'bar',
...);
$pageId = $pagesModel->insert($pagesData);
$fuseData = array('fuse_page' => $pageId,
'fuse_print' => $printId,
...);
$fuseId = $fuseModel->insert($fuseData);
thus is pseudo code, so you may want to move inserts into your models and do somoe i.e. normalisation etc.
I also suggest paying more attention to fields naming convention. It usually helps and now you got fuseid but also fuse_page. So it either should be fuse_id or fusepage (not to mention I suspect this field stores id so it would be fuse_page_id or fusepageid).
Prints and Pages are two entities . Create row clases for each
class Model_Page extends Zend_Db_Table_Row_Abastract
{
public function addPrint($print)
{
$fuseTb = new Table_Fuse();
$fuse = $fuseTb->createRow();
$fuse->fuse_page = $this->pageid;
$fuse->fuse_print = $print->printid;
$fuse->save();
return $fuse;
}
}
Now when you create page
$page = $pageTb->createRow() ; //instance of Model_Page is returned
$page->addPrint($printTb->find(1)->current());