This document will briefly introduce the common image formats used in Espressif software documentation built with ESP-Docs, describe their usage, and provide corresponding examples for writers’ reference.
Figures serve an essential role in conveying complex technical information. If you are writing some technical text and feel like expressing your ideas is getting increasingly harder (for example, while describing logical connections), consider using a diagram. Even the most complex ideas that are hard to understand when written as text can be quickly understood with the simplest of diagrams. The key to success is to choose the right diagram type for your case.
Luckily, diagrams in Espressif software documentation built with ESP-Docs already have more or less established styles.
There are different ways of rendering images in documentation:
- Directives to include ready-to-use pictures created by graphic editors.
- Diagram as Code to create diagrams based on textual descriptions for documents based on markup languages.
For detailed information about how to use these directives, please refer to Section Figure in the reStructuredText documentation. Below are some notes for writers when using the directives in our documentation.
For the ..figure:: directive, the path followed can either be a URL, or a relative path to your figures in the current project. For example, to link the specific figure under the _static folder, it can be written as:
.. figure:: ../../_static/doc-format1-recommend.png
or to access the separate server through the URL::
.. figure:: https://dl.espressif.com/dl/sche,atocs/pictures/esp32-s2-kaluga-1-kit-v1.0-3d.png
Note that, for the relative path, if you are not sure about it, please check in the terminal using ``cd ..``. For the URL, if the figures are too large, upload it to a separate server, then provide the URL.
Generally, for each repo, figures are stored in the ``_static`` folder. Below are some of the paths for your information:
- ESP-IDF: `esp-idf/docs/_static <https://github.com/espressif/esp-idf/tree/master/docs/_static>`_
- ESP-ADF: `esp-adf-internal/docs/_static <https://github.com/espressif/esp-adf/tree/master/docs/_static>`_
- ESP-AT: `esp-at/docs/_static <https://github.com/espressif/esp-at/tree/master/docs/_static>`_
- ESP-Docs: `esp-docs/docs/_static <https://github.com/espressif/esp-docs/tree/master/docs/_static>`_
- esp-dev-kits: `esp-dev-kits/docs/_static <https://github.com/espressif/esp-dev-kits/tree/master/docs/_static>`_
Note that if you use the ``... figure::`` directive to upload the non-editable diagrams (PNG, JPG, etc.), please remember to also upload the editable copy (SVG, ODG, etc.) with the same name as the non-editable diagrams uploaded to the internal image-storing GitLab repository corresponding to the current repository. It is also recommended to add a commented-out link to the editable copy in the figure directive for easier search. The reason why we are doing this is that while the editable copy could be too large to make the repository hard to pull, storing them in another repository could always be a fortune when the content of the document has changed and writers are able to find the original images and edit them at any time.
For the align: option, while another option, figclass:align- is sometimes used together in ESP-IDF, the priorities are listed below:
If the alignments are the same, such as :align:left and :figclass:align-left are used, then the figure will be aligned left.
If different alignments are defined, such as :align:center and :figclass:align-left are used, then the figure will be aligned center (top priority) > left > right (the lowest priority), as align: has a higher priority than figclass:align-.
Thus, it is recommended to use align: instead of figclass:align- in the documentation.
For the :scale: option, the default is “100%”, i.e. no scaling. As on the RTD page, only 700 px can fit into the page, figures should be scaled to get properly presented on HTML pages. To figure out the percentage of scaling that should be used, please check the width and height of the original figure. For example, if the dimension of the original figure is 3452*1590, then :scale:20% (which results in 690*318, smaller than 700 px) should be adopted to keep the right proportion presented on the page.
If a URL is provided as the figure path, and meanwhile the “scale” option is used, an error Couldnotobtainimagesize.:scale:optionisignored. might occur. At this time, you need to provide the image’s original width and height explicitly using :width: and :height: like below:
For the :alt: option, it shows the alternate description of figures. This description will be displayed when the figure is shown not properly on display. Normally, the caption of the figure would be placed here. If the figure is scaled, then the writer should also add (Click to enlarge) after the caption.
With this suite of tools, it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into “.png” graphics and integrated “behind the scenes” into Sphinx documents. Below is an example of Diagram as Code graphics in Espressif software documentation built by ESP-Docs:
If a blockdiag has lengthy code, it is suggested to save the code in a .diag file and provide the path to the file like in Section Driver Operation in ESP-IDF, which would reach exactly the same effects as well:
To conclude, while ready-to-use images drawn in graphic editors might be easier to handle for writers with little experience in creating diagrams, they have rather larger size based on their resolution. As for text-based Diagram as Code graphics, it would undoubtedly cost writers some time to get started and master, but they are smaller in size and easier to version with Git. Thus, it is recommended to use Diagram as Code to present pictures in your files.
