Add mcuboot_index.rst as workspace doc root

Add an MCUboot workspace-level document root file following
the pattern of Zephyr doc and file structure.  This file is
prefixed with the 'mcuboot_' (the module name) since the
Sphinx build system does not seem to guarantee which order
files are copied over from multiple source directories.

Verified by:

1. cd $mcuboot/zephyr/doc && rm -rf _build && \
     make html-fast && firefox _build/html/mcuboot_index.html &

Fixes #1512

Signed-off-by: Gregory Shue <gregory.shue@legrand.com>

zephyr/README.rst

@@ -0,0 +1,48 @@
+.. raw:: html
+
+   <a href="https://www.mcuboot.com">
+     <p align="center">
+       <img src="doc/_static/images/logo-readme.svg">
+     </p>
+   </a>
+
+   <a href="https://bestpractices.coreinfrastructure.org/projects/74"><img
+   src="https://bestpractices.coreinfrastructure.org/projects/74/badge"></a>
+
+
+MCUboot-on-Zephyr is the MCUboot secure bootloader for 32-bit microcontrollers
+ported into the Zephyr Project ecosystem. This port "project" includes:
+
+- a reusable Zephyr-specific boot application
+- integration of the common bootloader and flash layout infrastructure
+
+.. below included in doc/introduction/mcuboot_introduction.rst
+
+
+Getting Started
+***************
+
+Welcome to MCUboot-on-Zephyr! See the `MCUboot Introduction`_ for a high-level overview,
+and the documentation's `MCUBoot Getting Started Guide`_ to start developing.
+
+.. start_include_here
+
+Community Support
+*****************
+
+Community support is provided via mailing lists and Slack; see the Resources
+below for details.
+
+.. _mcuboot-resources:
+
+Resources
+*********
+
+Here's a quick summary of resources to help you find your way around:
+
+* **MCUboot Project Website**: https://mcuboot.com
+
+.. _MCUboot Documentation: http://docs.mcuboot.com
+.. _MCUboot Introduction: http://mcuboot.com
+.. _MCUboot Getting Started Guide: http://docs.mcuboot.com
+.. _MCUboot Contribution Guide: http://docs.mcuboot.com

zephyr/doc/conf.py

@@ -39,6 +39,7 @@
 project = "MCUboot-on-Zephyr Project"
 copyright = "2015-2022 Mcuboot and Zephyr Project members and individual contributors"
 author = "The MCUboot and Zephyr Project Contributors"
+root_doc = "mcuboot_index"
 
 # parse version from 'VERSION' file
 with open(MANIFEST_BASE / "VERSION") as f:
@@ -265,17 +266,27 @@
 # -- Options for zephyr.kconfig -------------------------------------------
 
 kconfig_generate_db = True
-kconfig_ext_paths = [ZEPHYR_BASE]
+kconfig_ext_paths = [ZEPHYR_BASE, MANIFEST_BASE]
 
 # -- Options for zephyr.external_content ----------------------------------
 
 external_content_contents = [
-    (ZEPHYR_BASE / "doc", "[!_]*"),
-    (ZEPHYR_BASE, "boards/**/*.rst"),
-    (ZEPHYR_BASE, "boards/**/doc"),
-    (ZEPHYR_BASE, "samples/**/*.rst"),
-    (ZEPHYR_BASE, "samples/**/doc"),
+    (b / "doc", "[!_]*") for b in (
+        ZEPHYR_BASE,
+        MANIFEST_BASE,
+    )
+] + [
+    (b, f) for b in (
+        ZEPHYR_BASE,
+        MANIFEST_BASE,
+    ) for f in (
+        "boards/**/*.rst",
+        "boards/**/doc",
+        "samples/**/*.rst",
+        "samples/**/doc",
+    )
 ]
+
 external_content_keep = [
     "reference/kconfig/*",
     "build/dts/api/bindings.rst",

zephyr/doc/introduction/mcuboot_introduction.rst

@@ -0,0 +1,56 @@
+.. _mcuboot_introduction:
+
+
+Introduction
+############
+
+MCUboot-on-Zephyr is the MCUboot secure bootloader for 32-bit microcontrollers
+ported into the Zephyr Project ecosystem. This port "project" includes:
+
+- a reusable Zephyr-specific boot application
+- integration of the common bootloader and flash layout infrastructure
+
+
+Licensing
+*********
+
+MCUboot is permissively licensed using the `Apache 2.0 license`_
+(as found in the ``LICENSE`` file in the
+project's `GitHub repo`_).  There are some
+imported or reused components of the MCUboot-on-Zephyr project
+that use other licensing as described in :ref:`Zephyr_Licensing`.
+
+.. _Apache 2.0 license:
+   https://github.com/mcu-tools/mcuboot/blob/main/LICENSE
+
+.. _mcuboot_GitHub repo: https://github.com/mcu-tools/mcuboot
+
+
+Distinguishing Features
+***********************
+
+MCUboot-on-Zephyr offers a significant set of features including:
+
+**First (Immutable) and Second (Mutable) Bootloader Configurations**
+
+**Multiple Crypto Algorithms**
+
+**Highly configurable / Modular for flexibility**
+   Allows an integration to incorporate *only* the capabilities it needs as it
+   needs them, and to specify their quantity and size.
+
+**Integration into Single- and Multi-threaded Executable**
+
+**Optional Recovery Application**
+   Allows developers and testers in a trusted environment to update a prototype
+   during early development and integration.
+
+
+.. include:: ../../README.rst
+   :start-after: start_include_here
+
+
+Fundamental Terms and Concepts
+******************************
+
+See :ref:`glossary`

zephyr/doc/mcuboot_index.rst

@@ -0,0 +1,121 @@
+..
+    MCUboot-on-Zephyr Project documentation main file
+
+.. _mcuboot_on_zephyr-home:
+
+MCUboot-on-Zephyr Project Documentation
+#######################################
+
+.. only:: release
+
+   Welcome to the MCUboot-on-Zephyr Project's documentation for version |version|.
+
+   Documentation for the latest (main) development branch of MCUboot-on-Zephyr
+   can be found at https://github.com/mcu-tools/mcuboot/.
+
+.. only:: (development or daily)
+
+   **Welcome to the MCUboot-on-Zephyr Project's documentation
+   for the main tree under development** (version |version|).
+
+Use the version selection menu on the left to view
+documentation for a specific version of MCUboot-on-Zephyr.
+
+
+.. raw:: html
+
+   <ul class="grid">
+       <li class="grid-item">
+	   <a href="introduction/index.html">
+	       <img alt="" src="_static/images/kite.png"/>
+	       <h2>Introduction</h2>
+	   </a>
+	   <p>Introducing the Zephyr Project: overview, architecture, features, and licensing</p>
+       </li>
+       <li class="grid-item">
+	   <a href="develop/getting_started/index.html">
+               <span class="grid-icon fa fa-map-signs"></span>
+	       <h2>Getting Started Guide</h2>
+	   </a>
+	   <p>Follow this guide to set up a Zephyr development environment on your
+	       system, and then build and run a sample application.</p>
+       </li>
+       <li class="grid-item">
+	   <a href="contribute/index.html">
+               <span class="grid-icon fa fa-github"></span>
+	       <h2>Contribution Guidelines</h2>
+	   </a>
+	   <p>As an open-source project, we welcome and encourage the community
+           to submit patches directly to the project.</p>
+       </li>
+       <li class="grid-item">
+	   <a href="samples/index.html">
+               <span class="grid-icon fa fa-cogs"></span>
+	       <h2>Samples and Demos</h2>
+	   </a>
+	   <p>A list of samples and demos that can run on a variety of boards supported
+	       by Zephyr</p>
+       </li>
+       <li class="grid-item">
+	   <a href="hardware/index.html">
+               <span class="grid-icon fa fa-sign-in"></span>
+	       <h2>Hardware Support</h2>
+	   </a>
+	   <p>Information about supported architectures, supported hardware and porting guides</p>
+       </li>
+       <li class="grid-item">
+	   <a href="security/index.html">
+               <span class="grid-icon fa fa-lock"></span>
+	       <h2>Security</h2>
+	   </a>
+	   <p>Requirements, processes, and developer guidelines for ensuring security is addressed within the Zephyr project.</p>
+       </li>
+       <li class="grid-item">
+	   <a href="boards/index.html">
+               <span class="grid-icon fa fa-object-group"></span>
+	       <h2>Supported Boards</h2>
+	   </a>
+	   <p>List of supported boards and platforms.</p>
+       </li>
+       <li class="grid-item">
+	   <a href="services/index.html">
+               <span class="grid-icon fa fa-puzzle-piece"></span>
+	       <h2>OS Services</h2>
+	   </a>
+	   <p>OS Services and guides how to use them with Zephyr</p>
+       </li>
+   </ul>
+
+Sections
+********
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   introduction/mcuboot_introduction.rst
+   develop/index.rst
+   kernel/index.rst
+   services/index.rst
+   build/index.rst
+   connectivity/index.rst
+   hardware/index.rst
+   contribute/index.rst
+   project/index.rst
+   security/index.rst
+   samples/index.rst
+   boards/index.rst
+   releases/index.rst
+
+   index.rst    # For Zephyr variant document root
+
+Indices and Tables
+******************
+
+* :ref:`glossary`
+* :ref:`genindex`
+
+.. _Apache 2.0 license:
+   https://github.com/mcu-tools/mcuboot/blob/main/LICENSE
+
+.. _GitHub repo: https://github.com/mcu-tools/mcuboot