New EVerest documentation #1591

Pietfried · 2025-11-28T09:58:08Z

Describe your changes

This PR introduces documentation sources and build tooling for the new EVerest documentation, which applies the diataxis format. Every part of the documentation is sorted into one of these categories:

Tutorials
How-To-Guides
Explanations
References

We started with the documentation skeleton in the branch-protected featrue/docs-migration branch a few weeks ago and reviewed and merged single documentation bits seperately into this branch, which now contains the composition of the changes.

Many parts of the existing documentation of https://everest.github.io/nightly/ has been reused and/or revised. A lot of additional documentation has been added:

Quickstart Guides for getting started with SW and HW
External API including generated reference documentation
BringUp & Qualification
Dedicated Linux / Yocto sections /
Cross-compilation
Subsystems of EVerest

and much more.

A preview of the documentation is available on https://everest.github.io/everest-core .

Issue ticket number and link

Checklist before requesting a review

I have performed a self-review of my code
I have made corresponding changes to the documentation
I read the contribution documentation and made sure that my changes meet its requirements

docs/source/explanation/linux-yocto/setting-up-linux-os.rst

…tory. (#1380) It is the foundation for the integration of more documentation bits from https://github.com/EVerest/EVerest into this structure. Changes include: * Docs build process and Sphinx configuration * Diataxis skeleton dividing every part of the documentation into: Explaination, How-to-guide, Tutorial, Reference * Added instructions how to build the documentation to everest-core README * Generation of reference documentation Signed-off-by: Krealyt <[email protected]> Signed-off-by: Andreas Heinrich <[email protected]> Signed-off-by: Piet Gömpel <[email protected]> Co-authored-by: Piet Gömpel <[email protected]>

* doc(explanation): Add community channels to docs Signed-off-by: Piet Gömpel <[email protected]> --------- Signed-off-by: Piet Gömpel <[email protected]> Co-authored-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

…inx (#1477) * Refactor _find_sphinx_build macro to allow system installation of sphinx Signed-off-by: Andreas Heinrich <[email protected]> * Fix setting of _SPHINX_BUILD_EXECUTABLE It needs to be a list, otherwise cmake will escape all whitespace which would then lead to a failure executing the command Signed-off-by: Kai-Uwe Hermann <[email protected]> --------- Signed-off-by: Andreas Heinrich <[email protected]> Signed-off-by: Kai-Uwe Hermann <[email protected]> Co-authored-by: Kai-Uwe Hermann <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

* doc(tutorial): Added Plug&Charge tutorial to docs --------- Signed-off-by: Piet Gömpel <[email protected]>

* doc(how-to): Add Configure Plug&Charge in EVerest --------- Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

* doc(tutorial): Add OCPP1.6 tutorial --------- Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

* doc(how-to): Add debug ISO15118 documentation --------- Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]> Co-authored-by: Piet Gömpel <[email protected]>

* doc(tutorial): Add develop new modules --------- Signed-off-by: Piet Gömpel <[email protected]>

* doc(linux/yocto): Added several documentation parts for Linux/Yocto integration --------- Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

…ging Regulations to documentation (#1494) Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

* doc(how-to): Add Renesas MPU docs --------- Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

… as part of EVerest doc (#1564) * docs(api): Move asyncapi spec and provide HTMLs as part of EVerest doc --------- Signed-off-by: Christoph Burandt <[email protected]>

…nt) (#1581) Signed-off-by: Christoph Burandt <[email protected]>

* doc(how-to): Add BringUp documentation for basic, ac, dc and powermeter bringup --------- Signed-off-by: Piet Gömpel <[email protected]>

* doc(explanation): Add adapt EVerest documentation --------- Signed-off-by: Piet Gömpel <[email protected]>

* doc(getting-started): Added Getting Started guides for SW and HW --------- Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Christoph Burandt <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

unresolved refs with "TODO") Signed-off-by: Christoph Burandt <[email protected]>

Signed-off-by: Christoph Burandt <[email protected]>

cburandt

Missing: The module configuration from originally #1432 which was closed in favour of #1492 which became #1577 after the security incident but never had the module configuration chapter.

cburandt · 2025-12-11T22:27:57Z

docs/source/explanation/getting-started/index.rst

+
+    get-started-sw
+    get-started-hw
+    /explanation/adapt-everest/index


This makes adapt-everest appear in the index for the second time (once below explanation and now also under explanation/getting-started)

cburandt · 2025-12-11T22:32:10Z

modules/EVSE/OCPP201/docs/index.rst

Some modules link to yaml files (like this one to manifest <../manifest.yaml>_.) - this does not work in the generated docs.

cburandt · 2025-12-11T22:34:48Z

docs/source/explanation/getting-started/index.rst

+   .. grid-item-card:: 🔌 EVerest APIs
+      :link: /explanation/adapt-everest/index
+      :link-type: doc
+
+      Learn about the APIs provided by EVerest that help you integrating
+      EVerest into your system and adapting it to your needs.
+


This links to both, EVerest APIs and Sub-Systems - change link name&explanation or remove the link (since it's linked on a higer level in the toc anyways)

I would like the APIs to be highlighted in the GettingStarted section. Removed it from the toctree

cburandt · 2025-12-11T22:35:54Z

modules/BringUp/BUDCExternalDerate/docs/index.rst

Remove index.rst for all BU modules or create them for each one?

Created it for all BU modules

cburandt · 2025-12-11T22:36:55Z

docs/source/qa/index.rst

Linked on the top-level index.rst, but not part of the TOC?

cburandt · 2025-12-11T22:39:55Z

docs/source/how-to-guides/bringup/basic.rst

+   Select PWM off / X1, switch EV simulator to state A.
+   This should output constant +12 V on the CP line.
+
+-  ☐ Select AC coupling on the scope and verify the ripple noise. There


These boxes look awkward (here and in some other rst files). I think, dynamic checkboxes are not possible in the resulting html.

Agreed, just using simple bullets now

cburandt · 2025-12-11T22:40:34Z

docs/source/explanation/getting-started/index.rst

+We provide several entry points for a fast start with EVerest.
+Whether you want to do a software-based simulation or start
+working with existing hardware, you will find your way here.
+


This is the only subpage with grid-itme-cards - on purpose?

It would probably be nice to have it for subpages explanation, how-to-guides, and tutorials as well.

I can do this.

cburandt · 2025-12-11T22:44:53Z

docs/source/how-to-guides/yocto-cross-compilation.rst

+.. tip::
+
+   You can download an SDK for the phyVERSO board here:
+   [SDK BaseCamp/phyVERSO](http://pionix-update.de/phyverso/1.0.0/phytec-ampliphy-rauc-glibc-x86_64-phyverso-basecamp-image-aarch64-toolchain-BSP-Yocto-Ampliphy-AM62x-PD23.2.1-phyVERSO-EVCS.sh).


since it's a link, it got to be what it is, but still a bit unfortunate that it uses "basecamp"

It was still a markdown link, fixed it.

cburandt · 2025-12-11T22:45:37Z

docs/source/how-to-guides/renesas-mpu/index.rst

+##############################################
+
+To get more information on EVerest and Renesas hardware, see here:
+https://www.renesas.com/en/products/microcontrollers-microprocessors/rz-mpus/rz-partner-solutions/pionix-basecamp


a bit unfortunate that it uses "basecamp" in the link

Signed-off-by: Piet Gömpel <[email protected]>

…ly to APIs Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Piet Gömpel <[email protected]>

Signed-off-by: Christoph Burandt <[email protected]>

Pietfried added the documentation Improvements or additions to documentation label Nov 28, 2025

movhdi reviewed Nov 29, 2025

View reviewed changes

docs/source/explanation/linux-yocto/setting-up-linux-os.rst Outdated Show resolved Hide resolved

Pietfried mentioned this pull request Dec 8, 2025

Integrate libocpp v0.31.1 into lib/everest #1611

Merged

3 tasks

krealyt and others added 27 commits December 8, 2025 16:04

(docs) add community channels (#1448)

4f9cdf8

* doc(explanation): Add community channels to docs Signed-off-by: Piet Gömpel <[email protected]> --------- Signed-off-by: Piet Gömpel <[email protected]> Co-authored-by: Piet Gömpel <[email protected]>

doc(pnc): Add Explaination of Plug&Charge in EVerest (#1429)

b2b03c9

Signed-off-by: Piet Gömpel <[email protected]>

doc(tutorial): Add bazel documentation (#1456)

a24907f

Signed-off-by: Piet Gömpel <[email protected]>

Add Plug&Charge tutorial documentation (#1439)

6825650

* doc(tutorial): Added Plug&Charge tutorial to docs --------- Signed-off-by: Piet Gömpel <[email protected]>

Add Configure Plug&Charge in EVerest documentation (#1428)

14c65bd

* doc(how-to): Add Configure Plug&Charge in EVerest --------- Signed-off-by: Piet Gömpel <[email protected]>

doc(explanation): Add devtool documentation (#1445)

3be6825

Signed-off-by: Piet Gömpel <[email protected]>

Add OCPP1.6 documentation (#1434)

e04f9d8

* doc(tutorial): Add OCPP1.6 tutorial --------- Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

doc(tutorial): Added OCPP2.x tutorial to docs (#1435)

c24a815

Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

Add ISO15118 debugging documentation (#1495)

d5d111a

* doc(how-to): Add debug ISO15118 documentation --------- Signed-off-by: Piet Gömpel <[email protected]>

doc(explanation): Add hardware architecture documentation (#1449)

64cfb96

Signed-off-by: Piet Gömpel <[email protected]> Co-authored-by: Piet Gömpel <[email protected]>

Add develop new modules to documentation (#1458)

8db28ce

* doc(tutorial): Add develop new modules --------- Signed-off-by: Piet Gömpel <[email protected]>

Add documentation for Linux/Yocto/Cross compilation (#1459)

26ae420

* doc(linux/yocto): Added several documentation parts for Linux/Yocto integration --------- Signed-off-by: Piet Gömpel <[email protected]> Signed-off-by: Piet Gömpel <[email protected]>

docs(explanation): Adds how-to guides for Eichrecht and UK Smart Char…

6d1e553

…ging Regulations to documentation (#1494) Signed-off-by: Piet Gömpel <[email protected]>

doc(explanation): Add High-Level EVerest overview to docs (#1453)

cc35ba3

Signed-off-by: Piet Gömpel <[email protected]>

Add renesas mpu docs (#1457)

6a5c5db

* doc(how-to): Add Renesas MPU docs --------- Signed-off-by: Piet Gömpel <[email protected]>

doc(how-to): Add security best practices to documentation (#1573)

ea4f982

Signed-off-by: Piet Gömpel <[email protected]>

docs(api): Move EVerest API asyncapi spec and build and provide HTMLs…

fe4c160

… as part of EVerest doc (#1564) * docs(api): Move asyncapi spec and provide HTMLs as part of EVerest doc --------- Signed-off-by: Christoph Burandt <[email protected]>

docs: fix various bugs (broken links, broken formating, missing conte…

d9ae41a

…nt) (#1581) Signed-off-by: Christoph Burandt <[email protected]>

Add basic BringUp documentation (#1576)

50dd232

* doc(how-to): Add BringUp documentation for basic, ac, dc and powermeter bringup --------- Signed-off-by: Piet Gömpel <[email protected]>

Add Adapt EVerest documentation (#1577)

af3eda1

* doc(explanation): Add adapt EVerest documentation --------- Signed-off-by: Piet Gömpel <[email protected]>

Add Getting Started documentation (#1574)

5146c77

* doc(getting-started): Added Getting Started guides for SW and HW --------- Signed-off-by: Piet Gömpel <[email protected]>

Formatting fixes in getting started docs

df022cf

Signed-off-by: Piet Gömpel <[email protected]>

Fix references in asnycapi docs

6908169

Signed-off-by: Piet Gömpel <[email protected]>

Move from doc.rst -> docs/index.rst in BUOcppConsumer and IMDSimulator

aec8919

Signed-off-by: Piet Gömpel <[email protected]>

Fix broken links

2aa90f7

Signed-off-by: Christoph Burandt <[email protected]>

Pietfried added 2 commits December 8, 2025 16:07

Add TSC section in community channels

0c45f04

Signed-off-by: Piet Gömpel <[email protected]>

Updated tsc resources

78eeca2

Signed-off-by: Piet Gömpel <[email protected]>

Pietfried force-pushed the feature/docs-migration branch from 8d0bce3 to 78eeca2 Compare December 8, 2025 15:07

Pietfried and others added 6 commits December 8, 2025 16:08

Updated repo to dev-hardware-yocto

3482bbe

Signed-off-by: Piet Gömpel <[email protected]>

Update headline

4299d7a

Signed-off-by: Piet Gömpel <[email protected]>

Update images

30b07f4

Signed-off-by: Piet Gömpel <[email protected]>

Fix TODOs and add EVerest APIs to Getting Started section

ce41cff

Signed-off-by: Piet Gömpel <[email protected]>

Minor fixes (links + avoid warnings, remove references to BC, mark

bf76ed2

unresolved refs with "TODO") Signed-off-by: Christoph Burandt <[email protected]>

Add OTA RAUC partitioning + drivers (from BC appendix)

37838e4

Signed-off-by: Christoph Burandt <[email protected]>

cburandt reviewed Dec 11, 2025

View reviewed changes

Pietfried and others added 7 commits December 12, 2025 09:41

added index.rst for all BU modules

af1ef07

Signed-off-by: Piet Gömpel <[email protected]>

Removed adapt everest from toctree and link in getting started direct…

c118fe6

…ly to APIs Signed-off-by: Piet Gömpel <[email protected]>

Add qa to toc

d247311

Signed-off-by: Piet Gömpel <[email protected]>

Remove checkboxes

f79c75c

Signed-off-by: Piet Gömpel <[email protected]>

Fix markdown link

930943b

Signed-off-by: Piet Gömpel <[email protected]>

Suppress sphinx warnings

678cf24

Signed-off-by: Christoph Burandt <[email protected]>

Fix visual appearance and some formatting violations

55cca87

Signed-off-by: Christoph Burandt <[email protected]>

New EVerest documentation #1591

Are you sure you want to change the base?

New EVerest documentation #1591

Uh oh!

Conversation

Pietfried commented Nov 28, 2025

Describe your changes

Issue ticket number and link

Checklist before requesting a review

Uh oh!

Uh oh!

cburandt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants