Python2 is no longer supported and hence the dependency
on six is no longer necessary.
According to https://six.readthedocs.io/#six.string_types,
six.string_types is just str in Python3.
According to https://six.readthedocs.io/#six.next in Python2.6
and above, six.next is just next.
Signed-off-by: Ivan Velickovic <i.velickovic@unsw.edu.au>
Explicitly select xml parser (instead of html) via "lxml-xml" in
BeatifulSoup to avoid warning.
Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
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
If no documentation is provided for the return value of a function, the
documentation generator will attempt to infer the documentation based on
the return type.
Gerwin Klein