Commit Graph

17 Commits

Author SHA1 Message Date
David B. Kinder a284123b72 doc: tweak known-issues for PDF processing
Update known-issues pattern for PDF processing to also work with updated
xelatex tools from Ubuntu 20.04

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-04-27 17:07:00 -07:00
David B. Kinder 0e317d56bf doc: clean up PDF generation for ACRN docs
PRs #5945 and #5949 introduced fixes to the doc building process to
support PDF generation of the documentation set.  This PR refines the
doc build process, cleaning up the Makefile, adding display of tool
version information, and updates the doc building documentation to
include additional dependencies needed for building the PDF and
instructions for how to build the PDF.  The latexpdf make target is
provided to just run the latex and PDF producing process that depends on
the HTML artifacts from a make html run.  A new make pdf target is
provided that combines the two steps into one.

A new know-issues pattern file is added that verifies the expected
output from the latexpdf process is returned, as it can't be completely
eliminated without losing potential error messages that need to be
resolved.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2021-04-26 19:50:44 -07:00
David B. Kinder c0707ab361 doc: prep for upgrading doc build tools
Update known-issues list to eliminate known warnings for duplicate
declaration warnings because of breathe/sphinx upgrades.

Update conf.py to check sphinx version and use appropriate way to
include extra javascript and css files depending on the version.

Both of these changes will allow the old and new doc tools to not show
unanticipated warnings or errors and allow for a smooth upgrade to the
CI system (and contributors local doc builds).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-12-31 13:04:27 -08:00
David B. Kinder ad8a0cf737 doc: doc cleanup for v2.3 release
Remove some stray Clear Linux references, document labels, and update
the known issue filter patterns.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-12-01 15:37:06 -08:00
David B. Kinder f2546384c8 doc: fix breathe config for C vs CPP
Breathe and doxygen work best for C++, but we're using C.  This shows up
as API documentaiton having a C++ flavor (modules and classes) instead
of the expected C flavor.  We really need to upgrade the versions of
doxygen and breathe to newer versions, and this configuration tweak
prepares for this.  (It will need CI coordination to update these tools,
but the changes in this PR are compatible with the current older tools.)

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-11-23 00:06:01 -08:00
David B. Kinder 791b091bbe doc: more prep for upgrading doc build tools
Preparing for upgrading to newer versions of doc building tools
including sphing, doxygen, breathe, docutils, etc.  This PR's changes
still work find with the older tool versions, but should eliminate
issues found while moving to newer tool versions (later).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-11-01 10:12:17 -08:00
David B. Kinder e2d3653976 doc: continue doc restructuring
Changing the folder structure will cause too many broken links for
external references (from other sites). So, let's put the content back
where it was before the reorg, and instead use the new persona-based
navigation to point to documents in the original locations.

Also, introduce redirects for some documents that no longer exits.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-08-01 14:07:22 -07:00
David B. Kinder cb6a3e8f08 doc: prepare for sphinx 2.0 upgrade
Sphinx 2.0 reports some "expected errors" differently, so add the new
message patterns to our known-errors scanning.

Also, the kerneldoc tool has a problem with sphinx 2.0, but a fix was
available.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2019-05-22 12:43:11 -07:00
David B. Kinder a86248ecd2 doc: hide doxygen duplicate definition warnings
Sphinx/Breathe have a known problem with processing unnamed nested
structs and unions that cause a "Duplicate definition" warning.

Use our .known-issues filter to hide these in the HLD content.

Tracked-on: #1706
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-11-01 20:55:11 -07:00
David B. Kinder 390cc67804 doc: tweak doxygen/known-issues handling
PR #1678 requires slight tweaking of doxygen/known-issues handling to
successfully generate documentation

Tracked-on: #1595
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-10-31 09:13:36 -07:00
David B. Kinder 1c54734f8b doc: update HLD Timer section
transcode, edit, and upload HLD 0.7 section 3.6 (Timer)
Also, fix the hv sections file names to be consistent.

Tracked-on: #1623

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-10-26 15:12:45 -07:00
David B. Kinder 9871b343fa doc: update I/O emulation section
Transcode, edit, and upload HLD 0.7 sections 3.4 (I/O emulation)
Add anchor targets to other docs reference in this section.
Update .known-issues filter for "known" doxygen/breathe errors

Tracked-on: #1592

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-10-25 13:39:33 -07:00
David B. Kinder 9c3d77e4b9 doc: tweek known-issues pattern for hypercall API
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-30 10:34:42 -07:00
David B. Kinder c776137169 doc: fix doc error filter patterns
Changes to hypercall.h altered the error pattern match used to decide if
doxygen errors are "expected".  Update the pattern match.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-07-23 10:42:55 -07:00
David B. Kinder ba7b4c7611 doc: adjust known issues pattern
Changes to the nested unnamed unions in type definitions require a tweak
to the pattern matching used to detect known issues reported by the API
doc generation.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-30 13:01:48 -07:00
David B. Kinder 66332aca00 doc: doxygen improvements and known issues hiding
Include more doxygen info, flag undocumented material, update
.known_issues matching for known doxygen/sphinx issues

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:25:54 +08:00
David B. Kinder 0dc93a5281 doc: filter known issues
make the doc build process quiet and add filtering of known (Sphinx)
issues.  Scripting comes from the open source Zephyr project.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2018-05-15 17:19:35 +08:00