docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md

   1 <!--
   2 /**-->
   3
   4 # Writing documentation for the DALi programming guide  {#documentationguide}
   5
   6 To allow documentation to be shared between C++ and JavaScript, please follow these guidelines:
   7
   8  - Create a mark down file (.md) using GitHub Flavoured Markdown https://help.github.com/articles/github-flavored-markdown/
   9  - Put it into the shared C++ / JavaScript documentation: dali-toolkit/docs/content/shared-javascript-and-cpp-documentation/~
  10  - Include code samples for both C++ and JavaScript in the mark down.
  11  - See script-overview.md overview in dali-toolkit/docs/content/shared-javascript-and-cpp-documentation for an example
  12  - For YUIDOC to parse the file it needs:
  13    - Enclosed in code comment block
  14    - Have a class tag with a description of the file
  15  - For DOXYGEN to link to the mark down it currently needs a reference {hash myfile}
  16
  17
  18 #### Images
  19  Images are shared between both Doxygen and YUIDOC tools using a symbolic link.
  20  You need to link to the image twice in shared documentation.
  21  This is because YUIDOC stores images in a folder called assets/img/  which is relative to the HTML pages.
  22  Where as Doxygen copies all images in to the same folder as the HTML generated pages.
  23
  24  ~~~
  25 ![ ](../assets/img/screen-shot.png)    // required for YUIDOC
  26 ![ ](screen-shot.png)                  // required for Doxygen
  27
  28 The space between the brackets is the alternative text. This means you will never see a broken image symbol.
  29 ~~~
  30
  31 ## Example
  32
  33 Please have a look at the numerous markdown files to see the header and footer requirements.
  34
  35 You can add tags to your headings as follows:
  36 ~~~{.md}
  37 # MyChapter {#my-chapter}
  38 ~~~
  39 Which will allow you to link to this section as follows:
  40 ~~~{.md}
  41 [Go To MyChapter](@ref my-chapter)
  42 ~~~
  43
  44 Code blocks can be enclosed within 2 blocks of 3 tildes(~).
  45
  46 You can even specify your language type, for example:
  47 ~~~{.md}
  48 ~~~{.cpp}
  49 ...
  50 ~~~{.js}
  51 ~~~
  52
  53 #### Why use GitHub flavoured markdown?
  54  - Table support is good and language specific code blocks are easier to define ( javascript/C++).
  55  - Doxygen and YUIDOC both support it.
  56
  57
  58 @class _Guide_Writing_DALi_Programming_Guide_Documentation
  59
  60 */