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>
Rather than a "tutorial", it was suggested to move the graphviz
information to the devleoper-guides, along with the documentation
guidelines. Makes sense.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Clear Linux is a stateless system, also systemd.
https://clearlinux.org/features/stateless
This tutorial advice to modify a file in /usr/lib which is used by vendors.
Instead of that, this commit advice to use the local administration
network directory at /etc/systemd/network.
See more reference using:
man systemd.network
Fixes: 25eae47836 ("Documentation: add tutorial to set up a static IP address")
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
Add a tutorial on how to change the default configuration that
uses DHCP and assign a static IP address to the system.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Fix a minor rendering issue in the Getting Started Guide where a
code-block is not appearing as such.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
We've been expanding documentation, and now need to organize things a bit
cleaner and separate content into new major folders: Introduction, Getting
Started, User Guides, Developer Guides, Tutorials, and Release notes..
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add some basic development tools needed to build the ACRN project.
These were not specifically called out (although most likely
already installed in any development system).
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Modify the Zephyr project script for creating documentation from Kconfig
files to generate the hypervisor option configuration docs. While Zephyr
uses a modified version of kconfiglib, we can use the standard
kconfiglib from Pypi (added to the requirements.txt file).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The latest versions of Sphinx and Breathe work well together so we're
updating the requirements.txt installation information (and
documentation) to use the latest versions of these tools.
Fixes: #395
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch adds two sections which describe how configurations can be modified
and how minimized configurations can be generated.
Also switch prerequisite python version from 2 to 3 since menuconfig.py is
python3 only.
v1 -> v2:
* Add the link to EPEL.
* Rename minimalconfig to savedefconfig in the guide.
* Split the step using a defconfig from those generating a defconfig.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
Acked-by: Geoffroy VanCutsem <geoffroy.vancutsem@intel.com>
On some system, the current doxygen configuration file will
generate a warning if CLANG_ASSISTED_PARSING was not enbabled
at compile time.
This is not used but the simple fact it's listed in the
configuration file (turned off) still generates the warning. So
comment out the option altogether to get a clean log output.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch adds a new target to build the documentation
from the top-level directory. Here is how to use it (from
the top-level source directory):
$ make doc
Or
$ make O=build-test doc
To clean all documentation build artefacts, simply call
$ make clean
Or
$ make O=build-test clean
Calling 'make' with no arguments will *not* build the
documentation by default.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch renames $(O) used in the documentation Makefile
(doc/Makefile) into $(OPTS) in order to avoid a namespace
conflict with $(O) used in the top-level Makefile.
This is in preparation to a new target called 'doc' that will
allow to build the documentation directly from the top-level
Makefile. This is required in order *not* to break setting a
specific build directory, e.g. 'make O=build-test'.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This update is to reflect the changes for acrnbridge to start
with systemd-networkd instead of running a script.
Signed-off-by: Tan Shen Joon <shen.joon.tan@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>
v4 -> v5:
* No changes.
v3 -> v4:
* No changes.
v2 -> v3:
* Update the guide before introducing the actual code.
v1 -> v2:
* Add guides on installing pip and kconfiglib.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Reviewed-by: Zhao Yakui <yakui.zhao@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>
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>
This continues the editing from PR #276 with formatting and clarity
edits to have these tool documents blend in with the rest of the ACRN
documentation. It also builds on PR #307 that set up the doc build
infrastructure to allow leaving these tool docs within the tools/
folder.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the Getting Started Guide to remove some instructions that
are now obsolete and add details of the cmdline parameters that
can be passed to the ACRN hypervisor (EFI), namely:
* bootloader=
* uart=
The wording of the GSG has been made less specific to the NUC
platform so we can refer to it for new platform being supported
without causing confusion to the reader
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Fix formatting and adhere to the recommendations published by
the documentation owner when writing reST documents.
Simplify the instructions by referencing the main Getting Started
Guide. This is now possible with the latest code since what
required us to modify the source code and build the components
are now parameters we can set when installing ACRN. This
simplifies the instructions *a lot*.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This adds basic information about the new ACRN tools that have
been integrated in the the acrn-hypervisor repo (under tools/).
It also adds the build dependencies for those tools in the
different development environment that we reference.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The tools documentation is maintained within the tools folder and
outside of the doc folder. We need to temporarily pull that content
within the doc folder for generating the documentation set. (We're using
a script developed for the Zephyr project for just this purpose.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The sambles scripts where moved to another directory but did not update
all the references in the documentation.
Fixes: 977d48d550 ("hypervisor: install acrn.efi to /usr/lib")
Fixes: 9563e248b7 ("samples: move samples to specifi platform diretory")
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
DM memory allocation mechanism is better placed in the Getting Started
material, so move it there from the primer.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
acrn.efi is a binary and need to be installed to /usr/lib instead of
/usr/share.
Suggested-by: Arzhan Kinzhalin <arzhan.i.kinzhalin@intel.com>
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
Move the platform apl-mrb samples to devicemodel samples directory.
Add the install target to the missing samples files and re-organize the
samples directory structure to have nuc and apl-mrb samples.
Suggested-by: Arzhan Kinzhalin <arzhan.i.kinzhalin@intel.com>
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.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>
Remove UEFI boot material that was causing doc build to fail (seems to
be a duplicate of material in the Getting Started Guide anyway)
Fix reST formatting for the DM memory allocation section.
Update folder layout description
Fixes: #202
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the "Contributing Guidelines" document to point at the
top-level LICENSE file that was created after the merger of
the three acrn-{hypervisor,devicemodel,documentation} repositories
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Post-merge, the doc building instructions need an update to reflect the
new diretory structure.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation updates were needed to account for changes caused by the
recent merging of the three acrn-hypervisor, acrn-devicemodel, and
acrn-documentation repos.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We've enabled GitHub issues for submitting and tracking bug and
enhancement requests for the project. Add some documentation about how
to use issues and what to expect.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Fix some formatting problems with a recent GSG update. Tweak the
custom CSS to adjust code block (and code literal) colors. Update
Makefile to document doc build options for pulling source from the other
repos and for publishing targets.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The boot process has changed a bit and the ACRN hypervisor is now
directly loaded by the platform EFI firmware. This commit reflects
those changes and also reference a newer version of Clearlinux that
includes the ACRN hypervisor that has these changes in.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
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>
Some assumptioins about the doc build process were removed to make it
easier for contributors to build local version of the docs. Assumption
now is that acrn-hypervisor and acrn-devicemodel content is up to date
rather than pulling from upstream on every build.
make pullsource will do an upstream pull manually
make html generates local docs
Also fixed broken link in the README.md file (moved the tech doc root)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
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>
David B. Kinder