Asciidoxy

=== Added

* Running AsciiDoctor automatically is now optional. By using `--backend adoc` the generated
AsciiDoc files are exported to the output directory, instead of the output of AsciiDoctor. This
allows direct use of the AsciiDoc by other tools. The generated AsciiDoc is now optimized for
this use case by not having any absolute paths, temporary files, and fragment files.
* *Experimental.* Replace the builtin templates for generating API reference with your own
customized versions. Provide a directory that overrides the builtin templates and allow
specifying a different template to use in the `insert` command.
* For increased performence in subsequent runs, generated python code for templates and input
documents is cached in the build directory. Use command line argument `--cache-dir` to set a
different location for the cache.
* Command-line arguments are exposed inside AsciiDoc files through the `config` object .


=== Changed

* Embedded files, inserted with `include` and `always_embed=True`, are no longer using temporary
files.
* Linking to an embedded file from outside the file where it is embedded is now possible iff the
file is embedded only once. If the file is embedded multiple times it can only be linked from
those files that embed it.
* Minimum supported python version is now 3.7. Python 3.6 is end of life.
* The Ruby interpreter is now started only once to process all generated AsciiDoc files. This
significantly decreases the time required to process a large number of pages in multipage mode.
* Unknown arguments are no longer passed through to AsciiDoctor. Commonly used arguments are
explicitly supported by AsciiDoxy now. If you need to pass additional arguments, use the `adoc`
backend to generate the AsciiDoc files and manually run AsciiDoctor on the output.


=== Fixed

* Removed unneccessary pass for partial matches when resolving references. Resolving references
is now almost instantaneous (on large code bases). The old pass was mostly finding incorrect
matches.

=== Added

* Completely rewritten description parser for Doxygen. It supports more kinds of tags and inserts
much less whitespace in the resulting AsciiDoc. It more closely follows the way Doxygen intends
to format the descriptions.
** Support `dot` and `plantuml` diagrams in Doxygen descriptions. They require
AsciiDoctor-Diagram to be rendered. In the Doxyfile the option `PLANTUML_JAR_PATH` is
required, even though Doxygen is not really rendering the plantuml diagrams. Without the
option, plantuml diagrams are ignored by Doxygen.
** Verbatim text in Doxygen descriptions is supported.
** Support special Doxygen paragraphs that are similar to AsciiDoc admonitions: `\attention`,
`\note`, `\remark`, and `\warning`.
** Support special Doxygen paragraphs that contain metadata: `\author`, `\bug`, `\copyright`,
`\date`, `\deprecated`, `\since`, and `\todo`. They are added to the overview table of
class-like elements, or the parameter table of functions/methods.
** Complex tables with cells spanning multiple columns and/or rows and nested tables (1 level)
are now supported.
** Support explicit line breaks in paragraphs.
** Support LatexMath formulae in Doxygen descriptions. It is required to enable `:stem:` in the
AsciiDoc header to render the formulae.
** Support images in Doxygen descriptions. Only `html` type images are shown, also for PDF
output. Make sure to include all images in the package containing the xml and specify the
`asciidoc.image_dir` option in `contents.toml`.
** Support MarkDown (preprocessed by Doxygen) in Doxygen descriptions. This adds support for:
headers, strikethrough, numbered and nested lists, horizontal rulers, and block quotes.
** Support special characters. This includes 250 characters that Doxygen represents with a
separate XML tag.
** Support HTML headings, preformatted text and other HTML specific styles.
** Support custom anchors.
** Support parameter descriptions consisting of multiple paragraphs.
** Respect output type specific content. Only content for XML and HTML output is used.
** Support Unicode emoji.


=== Changed

* Code blocks in descriptions try to respect the language specified in the original code. This
includes "unparsed" code blocks. Only if no language is specified, the language of the
described element is used.


=== Fixed

* Spaces in code blocks, present as `<sp />`, are no longer ignored.
* Actually create links to known exceptions from method/function documentation.
* 37: When type names contain nested types, and the nested types have namespaces, the short name
was incorrectly generated, resulting in incorrect section titles.
* 35: {Cpp}: Support typedefs for function types. Limitation: documentation for the function
parameters is missing. A planned refactoring will fix this.
* 31: Pipe symbols in documentation no longer cause tables to become malformed.

=== Added

- Provide detailed stack traces for links to missing elements. It should now be clear what
commands are causing the links to be inserted, especially when links are inserted as part of
another element's API reference.
- Provide detailed stack traces when inserting the same element multiple times. It should now be
clear whether the element was inserted as part of another element.
- Support preconditions and postconditions for functions and methods.


=== Changed

- Provide clearer errors and trace backs for exceptions while parsing AsciiDoc and for internal
errors.
- No longer use fragment files to include generated API reference. Instead, the generated
AsciiDoc is directly embedded in the processed AsciiDoc file.
- Extra AsciiDoc attributes are no longer supported for the `insert` command.


=== Fixed

- Do not generate empty "Members" section if there are no visible members.
- Fix running AsciiDoctor on Windows. Thank you r0ckarong!

=== Added

- Flexible anchors: With multi-page documents it can be hard to keep cross document references
working, especially when moving them between files. Using the new `anchor` command you can
create a flexible anchor that will be resolved by AsciiDoxy. Use `cross_document_ref` with only
an `anchor` to refer to flexible anchors.


=== Fixed

- Remove invalid downloaded packages from the cache. This solves an issue where a failed download
was never retried and required a manual purge of the build directory.
- Verify the contents of downloaded packages with `contents.toml`. Delete invalid packages from
the cache.
- Copying image files to an existing output directory no longer results in a file collision
error. File collision errors now contain more details about the packages causing the collision
and also report about files in the output directory that are not part of any package.
- Provide correct image directory to AsciiDoctor.

=== Fixed

- Objective C: Remove debug artefacts. This was causing layout problems in enclosed types.

=== Fixed

- Bring back character escaping in links.
- Improve character escaping in source blocks.
- [AD-56] Objective C: Fix visibility of enclosed types to match the enclosing type. Objects
exposed in a header file are always accessible.