contributing: template: Add eval template

Signed-off-by: Jorge Marques <[email protected]>

docs/contributing/creating_new_pages.rst

@@ -7,6 +7,19 @@ The first step on adding new content is to understand the
 :ref:`creating-new-pages documentation-structure`.
 Then, proceed with :ref:`creating-new-pages adding-content`.
 
+.. _creating-new-pages template:
+
+Content templates and guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Templates and guidelines for specific types of content are available:
+
+.. toctree::
+   :glob:
+   :titlesonly:
+
+   template/*
+
 .. _creating-new-pages documentation-structure:
 
 Documentation structure
@@ -29,7 +42,7 @@ To create each "volume", two
 `toctrees <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`__
 replicate the structure of the context top level.
 
-For example, while in :git-documentation:`docs/index.rst#L19-L25`
+For example, while in :git-documentation:`docs/index.rst#L24`
 we have:
 
 .. code:: rst
@@ -38,21 +51,23 @@ we have:
    .. toctree::
       :caption: Linux Kernel & Software
       :maxdepth: 2
+      :glob:
 
-      linux/kuiper/index
-      linux/drivers/index
-      linux/kernel/index
+      linux/*/index
 
-At the specific context toctree (:git-documentation:`docs/linux/index.rst#L6-L10`)
+At the specific context toctree (:git-documentation:`docs/linux/index.rst#L9`)
 we have:
 
 .. code:: rst
 
    .. toctree::
+      :glob:
+
+      */index
 
-      kuiper/index
-      drivers/index
-      kernel/index
+*Glob* is used to match any document that matches the pattern and avoids simple
+but annoying merge conflicts of contributors adding pages to the same toctree
+at the same time.
 
 Use case for the structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/contributing/template/eval.rst

@@ -0,0 +1,117 @@
+Evaluation Boards
+=================
+
+Evaluation boards pages compile all content related to an evaluation board,
+from the hardware overview, features, kit contents, hardware, user guides,
+developer guides, and source code.
+
+A top-level template is available at
+:git-documentation:`docs/contributing/template/example/eval.rst`
+(:ref:`rendered <template eval>`).
+Please pay attention to the comments only visible on the source code,
+and remove them as you follow the template.
+
+Base page structure
+-------------------
+
+Evaluation boards pages are divided into five main sections:
+
+* Overview
+* User Guide
+* Developer Overview
+* Developer Guide
+* Help and Support
+
+The evaluation board begins with an overview of the board, similar to the first
+paragraph at :adi:`analog.com </>`.
+
+The Overview section provides key points about the evaluation board to help the
+user understand it and choose the ideal solution (baremetal or Linux?, hard core
+or FPGA-based?, etc.).
+
+Then, cover key features, evaluation board kit contents, required equipment,
+hardware overview (all generic to all carriers).
+
+The "User Guide" section contains guides aimed at users, including those without
+deep technical knowledge. Start with the most plug-and-play solution,
+gradually diving deeper into technical aspects.
+If something is too technical, save it for the "Developer Overview" or
+"Developer Guide" sections.
+
+The "Developer Overview" section should provide all technical details that a
+developer may want to know and summarize and link all source code and
+documentation available.
+It's essential to leverage the :external+doctools:ref:`role git` and
+:external+doctools:ref:`in-org-ref`.
+Avoid using full URL paths, as they make consistency checks difficult.
+
+Similar to the "User Guide" section, the "Developer Guide" section contains
+guides but aimed at developers! Here is where you can really dive deep into the
+details and complex parts.
+However, make sure not to duplicate content already present on other pages,
+especially external ones.
+For example, the no-OS drivers' source repository already contains a page
+explaining the driver details.
+These developer guides should focus on intricate details of using the evaluation
+board with the solutions.
+
+Finally, the last section "Help and Support" contains generic information and
+links, but you can still add help/support information related to your particular
+evaluation board.
+
+Simplify the base structure
+---------------------------
+
+Some evaluation boards are simpler than others, and may not require splitting
+content into subpages.
+
+If the evaluation board in question does not contain or need a developer guide,
+then the "Developer Guides" section can be removed, and the "Developer Overview"
+renamed simply to "Developers" with pointers to the source code.
+
+Additionally, if there is only one carrier and user guide, the user guide can be
+integrated into the main page, replacing the carrier-agnostic paragraphs with
+the carrier-specific details.
+
+An example of this structure is :ref:`eval-adxl355-pmdz`.
+A more complex example is :ref:`eval-ad4052-ardz`.
+
+Structure Rationale
+-------------------
+
+This structure aims at minimizing content repetition, clearly defining the
+boundaries between "Plug&Play" solutions and highly-technical developer resources,
+and ensuring consistent linking to the source code and related documentation.
+
+It also enables generating custom documentations with only the pertinent content
+for the evaluation board, such as using Doctools'
+:external+doctools:ref:`custom-doc` with the following YAML file:
+
+.. code:: yaml
+
+   project: "EVAL-AD4052-ARDZ"
+   description: "Evaluating the AD4050/AD4052 Compact, Low Power, 12-Bit/16-Bit, 2 MSPS Easy Drive SAR ADCs"
+
+   include:
+     - documentation/eval/user-guide/adc/ad4052-ardz
+     - documentation/linux/drivers/iio-adc/ad4052
+     - hdl/projects/ad4052_ardz
+     - no-OS/drivers/ad405x.rst
+     - no-OS/projects/ad405x.rst
+
+   entry-point:
+     - caption:
+       files:
+         - documentation/eval/user-guide/adc/ad4052-ardz/index.rst
+     - caption: HDL Design
+       files:
+         - hdl/projects/ad4052_ardz/index.rst
+     - caption: Linux IIO Driver
+       files:
+         - documentation/linux/drivers/iio-adc/ad4052/index.rst
+     - caption: no-OS Driver&Project
+       files:
+         - no-OS/projects/ad405x.rst
+         - no-OS/drivers/ad405x.rst
+
+Produces a concise and resourceful user guide.