diff --git a/doc/Makefile b/doc/Makefile index 447b7eacc..afa7a8ca8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -32,7 +32,6 @@ help: # Generate the doxygen xml (for Sphinx) and copy the doxygen html to the # api folder for publishing along with the Sphinx-generated API docs. -#doxy: pullsource doxy: $(Q)(cat acrn.doxyfile) | doxygen - > doc.log 2>&1 diff --git a/doc/README.md b/doc/README.md index cf1cc7018..0207cc408 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,5 @@ -# Project ACRN Documentation Repo +# Project ACRN Documentation -This repository hold the source and configuration files used to generate the +This folder hold the source and configuration files used to generate the Project ACRN documentation web site published to https://projectacrn.github.io diff --git a/doc/contribute.rst b/doc/contribute.rst index c37739ab1..d286da9f9 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -107,7 +107,7 @@ as introduced in the project ACRN `Getting Started Guide`_. .. _Getting Started Guide: https://projectacrn.github.io/getting_started/ -You should be familiar with common developer tools such as Git, and +You should be familiar with common developer tools such as Git and platforms such as GitHub. If you haven't already done so, you'll need to create a (free) GitHub account @@ -116,20 +116,13 @@ on https://github.com and have Git tools available on your development system. Repository layout ***************** -To clone the ACRN hypervisor repository use:: +To clone the ACRN hypervisor repository (including the hypervisor, +devicemodel, and doc folders) use:: git clone https://github.com/projectacrn/acrn-hypervisor -To clone the ACRN device model repository use:: - - git clone https://github.com/projectacrn/acrn-devicemodel - -To clone the ACRN documentation repository use:: - - git clone https://github.com/projectacrn/acrn-documentation - -The project ACRN directory structure is described in the `Hypervisor -Primer`_ document. In addition to the ACRN hypervisor and device model itself, +The project ACRN directory structure is described in the :ref:`primer` +document. In addition to the ACRN hypervisor and device model itself, you'll also find the sources for technical documentation available from the `ACRN documentation site`_. All of these are available for developers to contribute to and enhance. @@ -137,9 +130,6 @@ developers to contribute to and enhance. .. _ACRN documentation site: https://projectacrn.github.io/ -.. _Hypervisor Primer: - https://projectacrn.github.io/hypervisor_primer - Submitting Issues ****************** @@ -223,8 +213,8 @@ and test your changes thoroughly before submitting. The general GitHub workflow used by project ACRN developers uses a combination of command line Git commands and browser interaction with GitHub. As it is with Git, there are multiple ways of getting a task done. We'll describe a typical -workflow here for the acrn-hypervisor repo that can also be used for the -acrn-devicemodel and acrn-documentation repos: +workflow here for the acrn-hypervisor repo, which includes the +source files for the hypervisor, devicemodel, and documentation: .. _Create a Fork of acrn-hypervisor: https://github.com/projectacrn/acrn-hypervisor#fork-destination-box @@ -232,6 +222,9 @@ acrn-devicemodel and acrn-documentation repos: #. `Create a Fork of acrn-hypervisor`_ to your personal account on GitHub. (Click on the fork button in the top right corner of the project acrn-hypervisor repo page in GitHub.) + When you want to submit a pull request with your changes, you'll + first submit them to your personal branch, and then to the project's + master branch for review and merging by the ACRN maintainers. #. On your development computer, clone the fork you just made:: @@ -251,6 +244,8 @@ acrn-devicemodel and acrn-documentation repos: git checkout master git checkout -b fix_comment_typo + Give your branch a short descriptive name. + #. Make changes, test locally, change, test, test again, ... #. When things look good, start the pull request process by checking @@ -260,9 +255,9 @@ acrn-devicemodel and acrn-documentation repos: Then add the changed files:: - git add [file(s) that changed, add -p if you want to be more specific] + git add [file(s) that changed] - (or to have all changed files added use):: + (or to have all changed files staged, use):: git add -A @@ -286,7 +281,7 @@ acrn-devicemodel and acrn-documentation repos: #. In your web browser, go to your personal forked repo and click on the Compare & pull request button for the branch you just worked on and you want to - submit to the upstream repo. + submit to the upstream ACRN repo. #. Review the pull request changes, and verify that you are opening a pull request for the appropriate branch. The title and message from your commit message should @@ -294,7 +289,8 @@ acrn-devicemodel and acrn-documentation repos: #. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS file in the repo). If you are a project member, you can select additional reviewers - now too. + now too. If no reviewers are selected, the ACRN triage team will + assign reviewers as appropriate. #. Click on the submit button and your pull request is sent and awaits review. Email will be sent as review comments are made, or you can check on your @@ -309,19 +305,24 @@ acrn-devicemodel and acrn-documentation repos: and use the same process described above to work on this new topic branch. -#. If reviewers do request changes to your patch, you can interactively rebase +#. If reviewers request changes to your patch, you can interactively rebase commit(s) to fix review issues. In your development repo, make the needed changes on the branch you made the initial submission:: git checkout fix-comment-typo - then:: + make the requested changes, and then:: git fetch --all git rebase --ignore-whitespace upstream/master - The ``--ignore-whitespace`` option stops git apply (called by rebase) from changing - any whitespace. Continuing:: + This is an important step to make sure your changes are properly + merged with changes from other developers that may have happened while you + were working on your changes. + The ``--ignore-whitespace`` option + stops ``git apply`` (called by rebase) from changing + any whitespace. If any merging issues are detected you can address them + with:: git rebase -i @@ -367,11 +368,7 @@ Changes are submitted as Git commits. Each commit message must contain: * If the change addresses an issue, include a line of the form:: - Fixes # - - See `Closing issues using keywords - `_ - for more information about this GitHub feature. + Fixes #. All changes and topics sent to GitHub must be well-formed, as described above. diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index cf53f4343..d312fe979 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -165,12 +165,12 @@ partition. Follow these steps: +-----------+----------------------------------------------------------------+ A starter acrn.conf configuration file is included in the Clear Linux release and is - also available in the acrn-hypervisor GitHub repo as `acrn.conf - `__ + also available in the acrn-hypervisor/hypervisor GitHub repo as `acrn.conf + `__ as shown here: - .. literalinclude:: ../../acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf - :caption: acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf + .. literalinclude:: ../../hypervisor/bsp/uefi/clearlinux/acrn.conf + :caption: hypervisor/bsp/uefi/clearlinux/acrn.conf On the NUC, copy the ``acrn.conf`` file to the EFI partition we mounted earlier: @@ -223,13 +223,13 @@ Without a network bridge, the SOS and UOS are not able to talk to each other. A sample `bridge.sh -`__ +`__ is included in the Clear Linux release, and -is also available in the acrn-devicemodel GitHub repo (in the samples +is also available in the acrn-hypervisor/devicemodel GitHub repo (in the samples folder) as shown here: -.. literalinclude:: ../../acrn-devicemodel/samples/bridge.sh - :caption: acrn-devicemodel/samples/bridge.sh +.. literalinclude:: ../../devicemodel/samples/bridge.sh + :caption: devicemodel/samples/bridge.sh :language: bash By default, the script is located in the ``/usr/share/acrn/demo/`` @@ -277,13 +277,13 @@ Set up Reference UOS #. Edit and Run the launch_uos.sh script to launch the UOS. A sample `launch_uos.sh - `__ + `__ is included in the Clear Linux release, and - is also available in the acrn-devicemodel GitHub repo (in the samples + is also available in the acrn-hypervisor/devicemodel GitHub repo (in the samples folder) as shown here: - .. literalinclude:: ../../acrn-devicemodel/samples/launch_uos.sh - :caption: acrn-devicemodel/samples/launch_uos.sh + .. literalinclude:: ../../devicemodel/samples/launch_uos.sh + :caption: devicemodel/samples/launch_uos.sh :language: bash :emphasize-lines: 22,24 @@ -368,17 +368,16 @@ Build the hypervisor and device model .. code-block:: console $ git clone https://github.com/projectacrn/acrn-hypervisor - $ cd acrn-hypervisor + $ cd acrn-hypervisor/hypervisor $ make PLATFORM=uefi The build results are found in the ``build`` directory. -#. Download the ACRN device model and build it. +#. Build the ACRN device model (included in the acrn-hypervisor repo): .. code-block:: console - $ git clone https://github.com/projectacrn/acrn-devicemodel - $ cd acrn-devicemodel + $ cd ../devicemodel $ make The build results are found in the ``build`` directory. diff --git a/doc/primer/index.rst b/doc/primer/index.rst index 33ed16f35..c3de30d73 100644 --- a/doc/primer/index.rst +++ b/doc/primer/index.rst @@ -59,6 +59,9 @@ ACRN hypervisor source tree ACRN Device Model source tree ============================= +**arch/x86/** + architecture-specific source files needed for the devicemodel + **core/** ACRN Device model core logic (main loop, SOS interface, etc.) @@ -92,6 +95,10 @@ reading now.) Developers can view this content either in its raw form as the HTML content and view it with a web browser directly on your workstation, useful if you're contributing documentation to the project. +**_templates/** + Sphinx configuration updates for the standard read-the-docs templates + used to format the generated HTML output + **api/** ReST files for API document generation @@ -103,8 +110,8 @@ workstation, useful if you're contributing documentation to the project. **getting_started/** ReST files and images for the Getting Started Guide -**primer/** - ReST files and images for the Developer Primer +**howtos/** + ReST files and images for Technical and Process how-to articles **images/** Image files not specific to a document (logos, and such) @@ -112,6 +119,9 @@ workstation, useful if you're contributing documentation to the project. **introduction/** ReST files and images for the Introduction to Project ACRN +**primer/** + ReST files and images for the Developer Primer + **scripts/** Files used to assist building the documentation set diff --git a/doc/scripts/publish-README.md b/doc/scripts/publish-README.md index 30a956837..bd16db17c 100644 --- a/doc/scripts/publish-README.md +++ b/doc/scripts/publish-README.md @@ -1,5 +1,6 @@ # projectacrn.github.io This is the Project ACRN Documentation Publishing site for GitHub Pages. Content changes are not made directly in this repo. Instead, edit content -in the acrn-documentation repo, re-generate the HTML with Sphinx, and push -the updated content here for publishing. +in the acrn-hypervisor repo's /doc folder, re-generate the HTML with +Sphinx (make html), and push the updated content here for publishing +(make publish)..