| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
Simple tweak to the Makefiles to allow "make doxygen" to work
natively on Macs - assuming the appropriate things have been
installed first, which it tests for.
Change-Id: I1a3e72759d533270a0512de38595c3bc3f71dee0
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
- Modularize the code to make the Siphon process easier to
maintain.
- Move much of the output rendering into Jinja2 templates.
- Add syscfg siphon type for startup config documentation.
- Add sample syscfg documentation.
- Add clicfg and syscfg preamble docs, adapted from their wiki pages.
- Fix sorting of CLI items across multiple directories.
Change-Id: Ib8288fe005adfea68ceed75a38ff8eba25d3cc79
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
Moves the random .md files, when rendered by Doxygen,
into a config examples tree. We may later flesh this
out into a more complete user documentation section.
Change-Id: If423b82f1047f1c84f90876a786313054b5f7c77
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
- The previous change only accounted for a missing Graphviz config
file; apparently it can be zero-sized too.
Change-Id: Ic6957d10cdc7cb7b9da72d2b2a0f8913100870c5
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
- Sometimes it seems Ubuntu doesn't always set up the Graphviz
handler config. If it's missing, generate it.
Change-Id: I2c1e566817de8415f8b360c6f967cd76307a2a52
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
- If present, include the directories where API header files
are generated into.
- Improve extraction of include paths from CPP
- Generalize the file/directory exclusion
This reduces some of the "warning" chatter from Doxygen.
Change-Id: I7ac02bff1639fe63f11263176020b0f040255017
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
- Fix issue in Doxy dependency check when nothing needs to be installed.
'set -e' and plain '[]' logic don't mix well.
- Fix Makefile snafu when building Doxy output for a single file.
- Include only one of vnet/vnet/buffer.c/dpdk_buffer.c in docs depending on
DPDKness. This could do with some improvement in future, eg to properly
align the pre-doxy steps with what Doxy does.
- Fix rendering of 'inline' tag in Doxygen by having it interpret
always_inline as "inline static".
- Bunch of duplicate CLI command structure names that confused docs and may
one day have caused debugging issues.
- Several other Doxygen syntax issues fixed, like documenting non-existant
parameters (usually just the wrong parameter name, typos, etc)
Change-Id: Ia8cca545e5de9f8750602bffa3c4548acc8971aa
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
Only try to install packages if they're not installed.
Saves a trip through sudo which is useful when you have a
non-privileged account generating the docs.
Change-Id: I3709aceb15516a45ea2f9510d91c6d2e42c8c349
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
Fixes various Doxygen warnings and other structural defects.
Note: This does not attempt to improve the content of the
documentation; only to improve the syntax and structure of it
and in some cases the consistency.
Change-Id: Ib1915f33edbdbc4558c85565de80dce323193906
Signed-off-by: Chris Luke <chrisy@flirble.org>
|
|
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>
|
|
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>
|
Chris Luke