8 Commits

Author SHA1 Message Date
Chris Luke
e0d802bc53 VPP-221 Loosen Doxygen CLI command struct parser
Make the struct parser slighty slightly more accomodating of
whitespace in places it has no business being.

Also add missing OS_ID thing to Doxygen makefile.

Change-Id: Id3d198fd926f7a6c2ed40bc2d08907aad5d5ac33
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-08-31 10:07:45 -04:00
Chris Luke
54ccf2261c VPP-221 CLI auto-documentation infrastructure
As a step before Doxygen, extract CLI-related struct initializers
from the code and parse that into a summary of the CLI commands
available with the provided help text, such as it is. At the moment
this only renders this into an indexed Markdown file that Doxygen
then picks up but later we can use this information to enrich the
existing VLIB_CLI_COMMAND macro documentor as well as provide
runtime documentation to VPP that is stored on disk outside the
binary image.

Additionally support a comment block immediately prior to
VLIB_CLI_COMMAND CLI command definitions in the form /*? ... ?*/
that can be used to include long-form documentation without having
it compiled into VPP.

Examples of documenting CLI commands can be found in
vlib/vlib/unix/cli.c which, whilst not perfect, should provide a
starting point. Screen captures of sample output can be seen at
https://chrisy.flirble.org/vpp/doxy-cli-example.png and
https://chrisy.flirble.org/vpp/doxy-cli-index.png .

Next, shift the Doxygen root makefile targets to their own Makefile.
The primary reason for this is that the siphon targets do dependency
tracking which means it needs to generate those dependencies whenever
make is run; that is pointless if we're not going to generate any
documentation. This includes the package dependencies since they since
they sometimes unnecessarily interfere with the code build in some cases
at the moment; later we will look to building a Python venv to host the
Python modules we use.

One final remark: In future we may consider deprecating .long_help
in the VLIB_CLI_COMMAND structure entirely but add perhaps .usage_help.
.short_help would be reserved for a summary of the command function
and .usage_help provide the syntax of that command. These changes would
provide great semantic value to the automaticly generated CLI
documentation. I could also see having .long_help replaced by a
mechanism that reads it from disk at runtime with a rudimentary
Markdown/Doxygen filter so that we can use the same text that is used in
the published documentation.

Change-Id: I80d6fe349b47dce649fa77d21ffec0ddb45c7bbf
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-08-31 12:56:56 +00:00
Keith Burns (alagalah)
f8a554f724 Add DPDK definition to DOXYGEN
Change-Id: I04e8663b49b5f706940b7aada0a7c2cae913a82b
Signed-off-by: Keith Burns (alagalah) <alagalah@gmail.com>
2016-08-06 14:36:10 -07:00
Chris Luke
4aa76c1c16 Fix missing include dirs in doxygen
Also allow a developer to alter the directories scanned at runtime to
facilitate shorter run-times when writing documentation.

Change-Id: I2a09519661a3abe1fbc0cfc294000934852af951
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-07-26 17:04:19 +00:00
Dave Barach
9770e20a9e Add some doxygen tags
Also add an index of node names

Change-Id: Id65c2e607976d8bad73deb738035a471be077196
Signed-off-by: Dave Barach <dave@barachs.net>
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-07-07 09:33:41 +00:00
Chris Luke
aa761e1281 VPP-57 Add missing license headers in doc files
Change-Id: Icd1f8952f66d3cee027c59f3148c67f1839de306
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-05-16 11:48:16 +00:00
Chris Luke
75a37b372e VPP-62 Add a doxy filter to enable vpe.api doc
This makes Doxygen think the API definitions are structs which is close
enough to be able to document the API methods.

It also has logic to create an indexed API page but that's disabled for
now because it duplicates the "brief" text twice in the struct doc.

Fixes a minor line numbering issue in filter_c.py.

Change-Id: If380160b73e7c10d999b35a76f55d0e27cbc91cc
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-05-15 13:22:54 +00:00
Chris Luke
b585097048 VPP-57 Add Doxygen to VPP
- Configures Doxygen.
- Adds a source filter to do magic on our use of the preprocessor to do
  constructor stuff to make Doxygen grok it better.
- Adds a convenience helper to the root Makefile.
- Adds a README.md to the root directory (and which Doxygem uses as its
  "mainpage".
- Add several other documentative files.
- Currently using SVG for call graphs, though this may have a
  load-time performance impact in browsers.

Change-Id: I25fc6fb5bf634319dcb36a7f0e32031921c125ac
Signed-off-by: Chris Luke <chrisy@flirble.org>
2016-05-13 17:23:36 +00:00