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>
Normal publication is to the /latest/ folder. With the tagged 0.1
release, we now have an alternative frozen version of the docs.
Also, tweaked the code for collecting version information from the
VERSION file to create document version number, and Makefile needed to
create the publish directory for a new tagged version.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Include developer comments, add commit change log,
update conf.py to include url shortcuts for references to GitHub issues
and commits.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
A recent PR changed where the release version is maintained (was in the
hypervisor/Makefile, now in a VERSION file) and format (was a RC_VERSION
variable, now a EXTRA_VERSION variable). The doc build process uses the
version information when generating documents.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some ACRN kernel components are using the API documentation methods of
the Linux kernel. While they use Sphinx for generating their
documentation, they don't use doxygen to collect the API information as
we do for the rest of the project. Instead, they use their own tools
called "kerneldoc". This PR incorporates those tools into our
documentation build process.
There is a prescribed directory structure for this to work: that the
acrn-hypervisor and acrn-kernel repos are cloned to sibling folders,
e.g.:
projectacrn
acrn-hypervisor
acrn-kernel
so that documentation references from acrn_hypervisor/doc can access the
source code in ../../acrn-kernel to do the kerneldoc processing. A full
display of the kerneldoc API material for a source file in the
acrn-kernel tree can be done using a sphinx extension directive:
.. kernel-doc:: /tools/virtio/linux/scatterlist.h
where the assumed root of these file references is ../../acrn-kernel.
The format for kerneldoc comments is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html and
references to kerneldoc API material in .rst files is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#including-kernel-doc-comments
Without options, the kernel-doc directive includes all documentation
comments from the source file. With options, you can display subsets of
these comments.
The intention is to limit use of kerneldoc comments to the acrn-kernel
repo and not use them elsewhere within the ACRN project (where doxygen
comments are expected.)
While I'd prefer NOT to include the kerneldoc perl script here (it is
already in the acrn-kernel/sphinx folder), I don't want to create a
dependency on the acrn-kernel folder existing for documentation
generation, but this might be unavoidable once we have part of the API
material coming from there. We can update this in a later PR.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Trying out the graphviz capability rather than using static images that
we can't easily modify. Also updated the site logo that was too wide.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
graphviz lets us create graphic images via a text language rather than
creating drawings in other tools (eliminating the need to keep the
sources for the images available, such as a powerpoint file).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add documentation contributing information with project specific
recommentations along with some common reST and Sphinx constructs.
Reorganize contributing section to fit this new doc in.
Also
* Cleanup stray file (CODEOWNERS) from when docs were in their own repo.
* Remove licensing footer on generated pages (not really needed).
* Pull replacement strings into substitutions.txt for easier management.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Tech note articles about technology and process tips now have a place in
the ACRN documentaion.
Move the doc process documention into this new area, and add a
placeholder for tech tips for now.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
add navigation to (manually) maintained list (in conf.py) of versioned
docs, and update generating and publishing processes to be
version-aware.
Adds a file to redirect root references to /latest folder now (since we
can't update the server redirects). Might break some links to pages
within the site from external sites.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Handle version retrieval better when comments are present.
Add warning if Sphinx theme (read_the_docs) is missing.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
