From df4e227855763f2a78d9858d962edfc8d652bc4e Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 8 Jun 2018 11:18:14 +1000 Subject: [PATCH] docs: Add "Creating Examples" docs page, template example README --- CONTRIBUTING.rst | 5 +- docs/TEMPLATE_EXAMPLE_README.md | 59 +++++++++++++++++++++ docs/en/contribute/creating-examples.rst | 36 +++++++++++++ docs/en/contribute/style-guide.rst | 18 ++++++- docs/zh_CN/contribute/creating-examples.rst | 1 + examples/README.md | 39 +++++++------- 6 files changed, 137 insertions(+), 21 deletions(-) create mode 100644 docs/TEMPLATE_EXAMPLE_README.md create mode 100644 docs/en/contribute/creating-examples.rst create mode 100644 docs/zh_CN/contribute/creating-examples.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 19dde17a9..3a9bd581d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -25,6 +25,8 @@ Before sending us a Pull Request, please consider this list of points: * Are comments and documentation written in clear English, with no spelling or grammar errors? +* Example contributions are also welcome. Please check the :doc:`creating-examples` guide for these. + * If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits `_? * If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback. @@ -51,5 +53,6 @@ Related Documents style-guide documenting-code + creating-examples ../api-reference/template - contributor-agreement \ No newline at end of file + contributor-agreement diff --git a/docs/TEMPLATE_EXAMPLE_README.md b/docs/TEMPLATE_EXAMPLE_README.md new file mode 100644 index 000000000..81bf6b342 --- /dev/null +++ b/docs/TEMPLATE_EXAMPLE_README.md @@ -0,0 +1,59 @@ +_Note that this is a template for an ESP-IDF example README.md file. When using this template, replace all these emphasised placeholders with example-specific content._ + +# _Example Title_ + +(See the README.md file in the upper level 'examples' directory for more information about examples.) + +_What is this example? What does it do?_ + +_What features of ESP-IDF does it use?_ + +_What could someone create based on this example? ie applications/use cases/etc_ + +_If there are any acronyms or Espressif-only words used here, explain them or mention where in the datasheet/TRM this information can be found._ + +## How to use example + +### Hardware Required + +_If possible, example should be able to run on any commonly available ESP32 development board. Otherwise, describe what specific hardware should be used._ + +_If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include links if applicable. Explain how to set them up._ + +### Configure the project + +``` +make menuconfig +``` + +* Set serial port under Serial Flasher Options. + +* _If there is any menuconfig configuration that the user user must set for this example, mention this here._ + +### Build and Flash + +Build the project and flash it to the board, then run monitor tool to view serial output: + +``` +make -j4 flash monitor +``` + +(To exit the serial monitor, type ``Ctrl-]``.) + +See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. + +## Example Output + +_Include an example of the console output from the running example, here:_ + +``` +Use this style for pasting the log. +``` + +_If the user is supposed to interact with the example at this point (read/write GATT attribute, send HTTP request, press button, etc. then mention it here)_ + +_For examples where ESP32 is connected with some other hardware, include a table or schematics with connection details._ + +## Troubleshooting + +_If there are any likely problems or errors which many users might encounter, mention them here. Remove this section for very simple examples where nothing is likely to go wrong._ diff --git a/docs/en/contribute/creating-examples.rst b/docs/en/contribute/creating-examples.rst new file mode 100644 index 000000000..69c0bbdae --- /dev/null +++ b/docs/en/contribute/creating-examples.rst @@ -0,0 +1,36 @@ +Creating Examples +================= + +Each ESP-IDF example is a complete project that someone else can copy and adapt the code to solve their own problem. Examples should demonstrate ESP-IDF functionality, while keeping this purpose in mind. + +Structure +--------- + +- The ``main`` directory should contain a source file named ``(something)_example_main.c`` with the main functionality. +- If the example has additional functionality, split it logically into separate C or C++ source files under ``main`` and place a corresponding header file in the same directory. +- If the example has a lot of additional functionality, consider adding a ``components`` directory to the example project and make some example-specific components with library functionality. Only do this if the components are specific to the example, if they're generic or common functionality then they should be added to ESP-IDF itself. +- The example should have a ``README.md`` file. Use the `template example README`_ and adapt it for your particular example. +- Examples should have an ``example_test.py`` file for running an automated example test. If submitting a GitHub Pull Request which includes an example, it's OK not to include this file initially. The details can be discussed as part of the PR. + +General Guidelines +------------------ + +Example code should follow the :doc:`style-guide`. + +Checklist +--------- + +Checklist before submitting a new example: + +* Example project name (in ``Makefile`` and ``README.md``) uses the word "example". Use "example" instead of "demo", "test" or similar words. +* Example does one distinct thing. If the example does more than one thing at a time, split it into two or more examples. +* Example has a ``README.md`` file which is similar to the `template example README`_. +* Functions and variables in the example are named according to :ref:`naming section of the style guide `. (For non-static names which are only specific to the example's source files, you can use ``example`` or something similar as a prefix.) +* All code in the example is well structured and commented. +* Any unnecessary code (old debugging logs, commented-out code, etc.) is removed from the example. +* Options in the example (like network names, addresses, etc) are not hard-coded. Use configuration items if possible, or otherwise declare macros or constants) +* Configuration items are provided in a ``KConfig.projbuild`` file with a menu named "Example Configuration". See existing example projects to see how this is done. +* All original example code has a license header saying it is "in the public domain / CC0", and a warranty disclaimer clause. Alternatively, the example is licensed under Apache License 2.0. See existing examples for headers to adapt from. +* Any adapted or third party example code has the original license header on it. This code must be licensed compatible with Apache License 2.0. + +.. _template example README: :idf_file:`/doc/TEMPLATE_EXAMPLE_README.md` diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst index bf0a2a018..6564bd083 100644 --- a/docs/en/contribute/style-guide.rst +++ b/docs/en/contribute/style-guide.rst @@ -183,9 +183,23 @@ Documenting code Please see the guide here: :doc:`documenting-code`. -Structure and naming --------------------- +.. _style-guide-naming: +Naming +------ + +- Any variable or function which is only used in a single source file should be declared ``static``. + +- Public names (non-static variables and functions) should be namespaced with a per-component or per-unit prefix, to avoid naming collisions. ie ``esp_vfs_register()`` or ``esp_console_run()``. Starting the prefix with ``esp_`` for Espressif-specific names is optional, but should be consistent with any other names in the same component. + +- Static variables should be prefixed with ``s_`` for easy identification. For example, ``static bool s_invert``. + +- Avoid unnecessary abbreviations (ie shortening ``data`` to ``dat``), unless the resulting name would otherwise be very long. + +Structure +--------- + +To be written. Language features diff --git a/docs/zh_CN/contribute/creating-examples.rst b/docs/zh_CN/contribute/creating-examples.rst new file mode 100644 index 000000000..1eceec548 --- /dev/null +++ b/docs/zh_CN/contribute/creating-examples.rst @@ -0,0 +1 @@ +.. include:: ../../en/contribute/creating-examples.rst diff --git a/examples/README.md b/examples/README.md index ead17f0b7..b164fc30f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,16 +1,28 @@ # Examples -This directory contains a growing number of simple example projects for esp-idf. These are intended to show basic esp-idf functionality, and to provide you can use for your own projects. +This directory contains a range of example ESP-IDF projects. These are intended to demonstrate parts of ESP-IDF functionality, and to provide code that you can copy and adapt into your own projects. + +# Example Layout + +The examples are grouped into subdirectories by category. Each category directory contains one or more example projects: + +* `bluetooth` contains Bluetooth (BLE & BT Classic) examples. +* `ethernet` contains Ethernet examples. +* `get-started` contains some very simple examples with minimal functionality. +* `mesh` contains Wi-Fi Mesh examples. +* `peripherals` contains examples showing driver functionality for the various onboard ESP32 peripherals. +* `protocols` contains examples showing network protocol interactions. +* `storage` contains examples showing data storage methods using SPI flash or external storage like the SD/MMC interface. +* `system` contains examples which demonstrate some internal chip features, or debugging & development tools. +* `wifi` contains examples of advanced Wi-Fi features. (For network protocol examples, see `protocols` instead.) # Using Examples -Building examples is the same as building any other project: +Building an example is the same as building any other project: -* Follow the setup instructions in the top-level esp-idf README. - -* Set `IDF_PATH` environment variable to point to the path to the esp-idf top-level directory. -* Change into the directory of the example you'd like to build. -* `make menuconfig` to configure the example. Most examples require a simple WiFi SSID & password via this configuration. +* Follow the Getting Started instructions which include building the "Hello World" example. +* Change into the directory of the new example you'd like to build. +* `make menuconfig` to configure the example. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). * `make` to build the example. * Follow the printed instructions to flash, or run `make flash`. @@ -18,7 +30,7 @@ Building examples is the same as building any other project: Each example is a standalone project. The examples *do not have to be inside the esp-idf directory*. You can copy an example directory to anywhere on your computer in order to make a copy that you can modify and work with. -The `IDF_PATH` environment variable is the only thing that connects the example to the rest of the `esp-idf` system. +The `IDF_PATH` environment variable is the only thing that connects the example to the rest of ESP-IDF. If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template). @@ -26,13 +38,4 @@ If you're looking for a more bare-bones project to start from, try [esp-idf-temp If you have a new example you think we'd like, please consider sending it to us as a Pull Request. -Please read the esp-idf CONTRIBUTING.rst file which lays out general contribution rules. - -In addition, here are some tips for creating good examples: - -* A good example is documented and the basic options can be configured. -* A good example does not contain a lot of code. If there is a lot of generic code in the example, consider refactoring that code into a standalone component and then use the component's API in your example. -* Names (of files, functions, variables, etc.) inside examples should be distinguishable from names of other parts of IDF (ideally, use `example` in names.) -* Functions and variables used inside examples should be declared static where possible. -* Examples should demonstrate one distinct thing each. Avoid multi-purposed "demo" examples, split these into multiple examples instead. -* Examples must be licensed under the Apache License 2.0 or (preferably for examples) if possible you can declare the example to be Public Domain / Creative Commons Zero. +In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example.