We no longer need to generate API documentation for the upstreamed
gvt-g kernel additions so we can remove the doc generation dependency on
the acrn-kernel repo (and all use of the kerneldoc extension). We also
remove GVT-g API documentation and porting guide that are obsolete with
ACRN v2.6 and referenced this API documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Tweak references to account for renaming the getting started guide in
PR #6226 and create a redirect link from the previous filename.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
This patch tweaks the settings in doc/conf.py to allow formatting the
documentation to a PDF file by Sphinx. The changes include:
- Use `xelatex` rather than the default `pdflatex` as the LaTeX engine, as
`pdflatex` is not that good at formatting non-ascii characters out of
the box.
- Use DejaVu fonts (which are available in common Linux distributions) in
the generated PDF.
- Restrict the depths of the table of contents to 3.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
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>
Automatically update the copyright year on the page footers to be
2018-[current_year] when generating documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
Links to files in the GitHub repo's master branch should be to the files
within the branch being generated. For example, in the v2.1
documentation, links should be to the v2.1 branch contents. (Previously
links were being made to the master branch in all our archived content.)
This creates a problem when we want to remove an obsolete file in the
master branch but can't because older documentaiton incorrectly depends
on it.
This new extension defines a :acrn_file: and :acrn_raw: role that will
create links to the given file within the current commit branch.
This PR also replaces docs with hard-coded links to files in the master
branch with uses of these new roles to create links to files.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some ACRN docs (in particular the HLD) has content nested more than the
4 levels shown in the sidebar navigation. So when looking at those
documents, it's hard to get to next chapter. Bring back the
previous/next links to fix this situation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
As a DX improvement in the documentation, include the release version
(or Latest) in the breadcrumb header on every page. This can help
readers know which release version documentation they're using.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
As we're removing Clear Linux docs because of removing depriviliged boot
mode support, we can refer folks to the last known version of these docs
in the v2.1 release instead of just throwing a 404 error.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Improve usability of search results to promote tutorials and developer
guides, and demote API and KConfig material, with release notes at the
end.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Move the rt_industry GST into a tutorial for using Clear Linux as the
Service VM. Also drop a redirect to avoid 404 errors reference the
moved doc (redirect list maintained in conf.py)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The sphinx-tabs extension let's us create a document that can
dynamically display alternate material based on clicking a tab, as used
in the Zephyr getting started guide:
https://docs.zephyrproject.org/latest/getting_started/index.html
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We've been keeping the doc version choice list trimmed as new doc
version releases are made, but the v1.0 version should remain. (Note
that the documents for all previously published versions are still
available on the server, but they were included in the menu choice).
This PR puts the 1.0 choice back in.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
PR #3665 moved all the doc build artifacts into the _build folder and
updated scripts and Makefile to account for this, except missed a fix in
the script that checks for known issues. This patch fixes that but shows
we've got a bunch of issues that have not been being reported so we'll
need to fix those problems to resolve failing doc builds.
Also fixed process of the VERSION file in conf.py since the path to that
file was changed by PR #3665 as well and was raising an exeception that
was being masked.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
A few more tweaks to the site navigation since we moved the content back
to its original folder structure.
Remove the temporary "doc reorg in progress" banner.
Add reference to hardware in the "try" section.
Add link to the documentation home page in left nav pane.
Add additional redirects to handle external links to moved content.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
Update the /latest/ (master) version of the docs to provide the menu
choice for the v1.1 release.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
When 0.8 documents are published, we create a link to them from the
master branch where the /latest version of documentation is found.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The Sphinx .. only:: directive is limited to handling only conditional
text and can't handling conditional use of directives. For example,
.. only:: test
.. automodule:: west.runners.core
:members:
is not handled. This PR monkey patches the handling of the existing
.. only:: directive done by Sphinx.
See https://github.com/pfalcon/sphinx_selective_exclude for details.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update conf.py selector list to include version 0.2 documentation (and
fix an URL typo in the release notes).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
In special cases, we'd like to freeze doc versions based on a tag (e.g.,
tags/acrn-2018w34.4-140000p) and have that version show up on the
generated docs. (Normally the version shown is from the
hypervisor/VERSION file.)
With this patch, if DOC_TAG=release then it uses a RELEASE=name
environment variable (e.g., from the make command line) to override the
displayed version:
make DOC_TAG=release RELEASE=acrn-2018w34.4-140000p html
make DOC_TAG=release RELEASE=acrn-2018w34.4-140000p publish
Assuming you've checked out the tagged branch (both for acrn-hypervisor
and acrn-kernel), these make commands will generate and publish docs to
https://projectacrn.github.io/acrn-2018w34.4-14000p
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
David B. Kinder