Feature/1512 zephyr doc build #1513
Conversation
Initial documentation build for zephyr-based MCUboot workspace.
This initial commit builds the zephyr documentation from this
module docs directory following the same procedures as for
building Zephyr documentation from the zephyr/ repository.
Verified by:
1. cd $mcuboot/zephyr/doc && make html-fast && \
firefox _build/html/index.html &
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
Add "$mcuboot/zephyr/VERSION" for Zephyr-style manifest-module versioning
and publication in documentation.
Add MCUboot-local zephyr/doc/conf.py for local configuration control.
This file is a copy of Zephyr's conf.py with the following changes:
- Multiple text strings modified for MCUboot:
- project
- copyright
- author
- html_title
- index-tex
- Zephyr releases removed from html_context.versions
- ZEPHYR_BASE picked up from OS environment
- MANIFEST_BASE passes along local "$mcuboot/zephyr/" path
- "$mcuboot/zephyr/VERSION" used for doc version
Verified by:
1. cd $mcuboot/zephyr/doc && rm -rf _build && \
make html-fast && firefox _build/html/index.html &
+ Confirmed expected content was displayed (incorrect styling)
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
Add and use "$mcuboot/zephyr/doc/_templates" and
"$mcuboot/zephyr/doc/_static" content to resolve style issues.
Verified by:
1. cd $mcuboot/zephyr/doc && rm -rf _build && \
make html-fast && firefox _build/html/index.html &
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
Verified by:
1. cd $mcuboot/zephyr/doc && rm -rf _build && \
make html-fast && firefox _build/html/index.html &
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
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 mcu-tools#1512
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
|
What is the controversy? |
There was a problem hiding this comment.
Why should the MCUboot docs change ?
There is already a Readme for MCUboot with Zephyr here: https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-zephyr.md
which follows the same pattern as any other project:
https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-espressif.md
https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-mbed.md
https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-mynewt.md
etc.
As it's seen then MCUboot is used by many projects, and starting to have such integration documentation for each project in MCUboot is going to be a never ending task.
MCUboot provides a nice overview here:
https://github.com/mcu-tools/mcuboot/#mcuboot-how-tos
If a project wants to adjust the look of the MCUboot doc pages, then I think it should be the responsibility of that project.
See for example how nRF Connect SDK compiles several docsets into one, including Zephyr and MCUboot:
https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/mcuboot/index-ncs.html
One controversial commit is 8e667d3 .
That commit is a pure copy of files from Zephyr ,why ?
At some point in future, Zephyr will progress and then those files are no longer in sync with their Zephyr counterparts.
Who will ensure those files are kept in sync ?
Duplicating files between repos should generally be avoided / minimized, and in above commit we are talking about copying 14 files / >5200 LOC.
I fail to see what extra knowledge readers are getting with this commit:
84a4516
compared to the existing MCUboot docs and project specific docs linked above.
I propose to reject this PR due to the duplication of massive loc, and the fact that the extra doc provides no extra information to the reader.
The request for #1512:
I need to generate comprehensive documentation to go along with the solution I deliver to customers,
so that I can minimize the support I need to give when my customer eventually tries to use, port, and/or modify the delivered code.
is already possible in today's solution without this amount of duplicated files, as it has been shown in above screenshot and link.
That screenshot is for NCS documentation system, not Zephyr's documentation system. IIRC from Carles' comments a while ago, Nordic documentation system had to introduce substantial changes from Zephyr to support what you reference. AFAICT, this is the simplest way to extend Zephyr's documentation system for workspace-level documentation.
The duplications are there because some content needed to be tailored and the current system required content to come over in relatively large blocks. I reused whatever I didn't expect to need tweaking. I copied only what I must, given the current Zephyr documentation system design.
The documentation process is also involved in requirements tracing, so it is not only about "knowledge".
All the copied data is now custom to the receiving repository. It is up to the maintainers to decide if they care if it is in sync with the original source. If they care, it is up to them to do the update. This is downstream of Zephyr, so Zephyr Project isn't concerned with this. |
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
Fixes #1512 .