This way common error codes can be in their own file.
To use, add the xmlns:xi="http://www.w3.org/2001/XInclude
attribute to the top level node and use:
<xi:include href="file-to-include.xml"/>
The content of the file will be included verbatim.
Include files must be complete XML documents, but without
<?xml version="1.0" ?> at the top. Practically this means
all nodes within the file need to be contained in one root
element.
Caveat: There is no proper dependency for Xincludes files in
the Makefile, so you need to do make clean after changing an
included XML file!
Signed-off-by: Indan Zupancic <indan@nul.nu>
Put MCS-only invocations into their own groups and files. This solves
the problem that doxygen gets confused by duplicate function names with
the same parameters.
MCS/non-MCS is distinguished by evaluating the <condition> field in the
API XML definition. If the condition evaluates to true when
CONFIG_KERNEL_MCS is set, it is an MCS-only method, otherwise it is
assumed to be non-MCS or present in both configs.
Fixes#558
Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
Different API groups may contain the same function name, for instance
IRQ_Control GetTrigger for RISC-V vs the same for ARM. Duplicate
function names with identical parameter lists confuse doxygen, leading
it to generate a single merged xml entry for both, which means one of
the entires will be missing and the other will be potentially wrong.
When the functions are placed in different files and different groups
at the same time, doxygen no longer is confused in all cases.
Therefore:
- generate a separate file for each API group
- generate a separate file group_defs.h that contains group definitions
and declares group nesting
Unfortunately, this does not seem to always work (e.g. the toplevel
MCS/non-MCS syscalls), so manual inspection is still necessary when
adding new calls and separate doxygen runs for duplicate function names
may be necessary. Generating separate files as above enables this
option, should it become necessary in the future.
Fixes#530
Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
Explicitly select xml parser (instead of html) via "lxml-xml" in
BeatifulSoup to avoid warning.
Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
Guard the new implementation of 64-bit x86 guests behind a config
option. This is done so that existing projects that use x86_64 hosts
with ia32-bit guests can continue to be supported until either the old
feature is preferred to be deprecated, or support can be added to
support both simmultaneously.
Signed-off-by: Kent McLeod <kent@kry10.com>
Extra spaces are inserted after texttt tags when generating doxygen
comments in order to ensure that xmlonly tags are readable by doxygen.
The extra spaces cause a description like this:
```
Testing <texttt text="1"/>, 2, 3
```
To be rendered like this:
```
Testing 1 , 2, 3
```
This change identifies text runs that start with extra spaces and either
a period or a comma and removes the extra spaces, allowing at least
common punctuation to be rendered correctly.
Signed-off-by: Jimmy Brush <code@jimmah.com>
This commit also converts our own copyright headers to directly use
SPDX, but leaves all other copyright header intact, only adding the
SPDX ident. As far as possible this commit also merges multiple
Data61 copyright statements/headers into one for consistency.
Previously the manual would only parse the doxygen for a single xml
file, which meant references to symbols on other files would break.
Parse all doxygen files when constructing the ref dict to fix this.
Update all scripts and build system to call python3, given python2's
upcoming doom. Use sys.maxsize instead of sys.maxint in one script
(maxint does not exist in python3).
This change generates doxygen groups for each object type, which allows us to create sections in
output documents for each object. This has the advantage that we can later label those sections and
link to them from the main document. Additionally, it improves nagivation of the API docs.
The level argument to parse_doxygen_xml.py was previously a latex section header (either subsection
or subsubsection). This change converts the argument to numerical which is more robust and is not
limited to 2 specific levels.
This change
- alters the level argument to be an int, where 0 = highest level header,
- removes the translation of latex header to markdown,
- adds a new 'level_to_header' function to the generator class, which translates the level number
to a header for that specific output type.
Added a command line option for the user to specify the output
format i.e markdown or latex. The command option is used to either
create a Latex or Markdown class.
Added Markdown Generator implementation. This is a child class
to the Generator class. The Markdown generator class overrides
specific parsing table elements and methods to achieve Markdown
specific output, similar to the Latex Generator.
Updated the text_escape function to regex escape characters in the
generators escape set. This is for the case when a generators
special character set collides with regex's special character
set.
Introduced a new Doxygen XML tag '<docref>'. The intention of
this tag is to indicate a section of text in the Doxygen XML that
will contain a reference to another section in the Manual e.g.
"See \autoref<sec:x>". As other generation formats aren't aware of
other chapters/sections in the manual, the <docref> encapsulation
allows it to omit the text from the output. The Latex generator
has been modified to continue parsing the 'docref' contents.
The option to escape the text when parsing the prototype can be
specified to the parse_prototype function. Markdown does not
require special C code characters to be escaped.
Moved Latex specific param string generation out of the Generator
class. Added functions to generate the desired param string
format that the Latex class can then override.
Implemented LatexGenerator child class which extends the
Generator class. The Latex class overrides methods of the
Generator with Latex specific format. Currently a lot of
duplication between Generator and Latex class, need to
generalise the Generator class.
New generator classes are expected to override the ESCAPE_PATTERNS
variable. Moving the regex into an object method allows it to use
the overriden escape patterns.
Parameterised the generator class for the
'generate_general_syscall_doc' method. This will allow the caller
to pass the desired generator to the function.
Moved api doc string format into a seperate function within the
Generator class. This will allow new generators to override the
function with their own api doc format.
Moved the parsing functionality into a object. The goal is to
refactor the script into an object model such that we can extend
and override parsing functions to output the doxygen to different
formats. Additionally updated the various methods and variable
accesses to use 'self' inorder to work in the new object oriented
paradigm.
Previously anything in an autoref block was assumed to reference
a section, which isn't true. Change 'sec' to 'label' and move the
'sec' prefix into the label itself.
- use 'recursive=False' rather than 'content' to only search children
- use a parse table instead of if a long if/else
- fix nested lists
- use get_text from beautiful_soup rather than home brewed
- don't call latex_escape explicitly
