RFC: Improving sample documentation


Nashif, Anas
 

Hi,

Here is a quick proposal for improving documentation of samples and integrating them into the online documentation available on zephyrproject.org. The RFC is also tracked in Jira under

https://jira.zephyrproject.org/browse/ZEP-1523

I am including the full text here in case someone wants to comment inline.

I was using one existing sample as reference, it can be found here in Gerrit:

https://gerrit.zephyrproject.org/r/#/c/9676/3/samples/environmental_sensing/README.rst

comments welcome


-----

h2. Rationale

Many samples in the Zephyr tree have a README in free form or follow some legacy syntax that duplicates a few common sections and mostly targets building and running the sample in an emulated environment using QEMU.

As we expand support for boards in the Zephyr project and the complexity of samples and their hardware requirement grows, more detailed and consistent documentation is required.
Documentation of the samples should not be limited to the use case of opening a README using an editor, instead we want to make samples and their documentation available as part of the online Zephyr documentation on the main website and also create them in a way that would allow automated formatting when viewed in different environments, for example on github.com.

h2. Proposal

# All samples and demos shall have documentation
# Documentation of a sample shall reside in the root of the sample source directory, alongside the Makefile
# The name of the documentation file for a sample shall be: README.rst
# All samples, demos and tutorials included in the Zephyr project shall use the reStructuredText syntax for documenting the sample purpose and how it can be used
# All samples shall use the document structure provided below
# A sample shall provide instructions for at least one target platform
# A sample shall provide the expected output on the console or the expected behaviour of the attached hardware.
# A sample shall provide a list of all required hardware and software components to build and operate the sample on the supported target platforms


h2. Documentation Structure

[A Descriptive Title]
################

Overview
========
[A short description about the sample and what it does]

Requirements
============
[List of required software and hardware components. Provide pointers to hardware components such as sensors and shields]

Wiring
======
[For simple projects, a description of how to wire the board for the demo. For complex projects, provide a graphic with more details, preferably using Fritzing or some other visualisation tools]

Building and Running
==================
[ How to build the sample and how to run it. Pointers to where to find the sample in the source tree and how to configure it and run it for a specific target platform]

References
=========
[ Links to external references such as datasheets or additional documentation]

Join devel@lists.zephyrproject.org to automatically receive all group messages.