{"action":"created","issue":{"url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/7","labels_url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/7/labels{/name}","comments_url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/7/comments","events_url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/7/events","html_url":"https://github.com/opentx/lua-reference-guide/issues/7","id":114988464,"number":7,"title":"A process to generate function documentation from the sources","user":{"login":"projectkk2glider","id":5950438,"avatar_url":"https://avatars.githubusercontent.com/u/5950438?v=3","gravatar_id":"","url":"https://api.github.com/users/projectkk2glider","html_url":"https://github.com/projectkk2glider","followers_url":"https://api.github.com/users/projectkk2glider/followers","following_url":"https://api.github.com/users/projectkk2glider/following{/other_user}","gists_url":"https://api.github.com/users/projectkk2glider/gists{/gist_id}","starred_url":"https://api.github.com/users/projectkk2glider/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/projectkk2glider/subscriptions","organizations_url":"https://api.github.com/users/projectkk2glider/orgs","repos_url":"https://api.github.com/users/projectkk2glider/repos","events_url":"https://api.github.com/users/projectkk2glider/events{/privacy}","received_events_url":"https://api.github.com/users/projectkk2glider/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"projectkk2glider","id":5950438,"avatar_url":"https://avatars.githubusercontent.com/u/5950438?v=3","gravatar_id":"","url":"https://api.github.com/users/projectkk2glider","html_url":"https://github.com/projectkk2glider","followers_url":"https://api.github.com/users/projectkk2glider/followers","following_url":"https://api.github.com/users/projectkk2glider/following{/other_user}","gists_url":"https://api.github.com/users/projectkk2glider/gists{/gist_id}","starred_url":"https://api.github.com/users/projectkk2glider/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/projectkk2glider/subscriptions","organizations_url":"https://api.github.com/users/projectkk2glider/orgs","repos_url":"https://api.github.com/users/projectkk2glider/repos","events_url":"https://api.github.com/users/projectkk2glider/events{/privacy}","received_events_url":"https://api.github.com/users/projectkk2glider/received_events","type":"User","site_admin":false},"milestone":null,"comments":3,"created_at":"2015-11-04T07:17:16Z","updated_at":"2015-11-08T13:04:10Z","closed_at":null,"body":"Original idea came from Bertrand. \r\n\r\nWe should try to develop a system that allows us to document OpenTX Lua API functions in the source code files (like Doxygen style documentation) and then have a python script that will auto-generate files and their contents in markdown format that will be directly useable in the gitbook.\r\n\r\nOther parts of the Lua manual will still be developed in the current way. So the automatic docs generation would only document the https://github.com/opentx/lua-reference-guide/blob/master/part_iii_-_opentx_lua_api_reference.md\r\n\r\nSo the process would be:\r\n* write documentation for each Lua exported function in the source code, rigth there where the actual function implementing it is defined. This way we have a better chance to keep the actual function functionality and it's documentation in sync.\r\n* in-source documentation format is still yet to be decided, possible options are:\r\n  * directly use the markdown\r\n  * use (simplified) Doxygen format\r\n* when we decide to update the docs (gitbook) we run the custom python script that will:\r\n  * parse lua_api.cpp file from OpenTX repository\r\n  * look for special comment sections that contain documentation\r\n  * parse and format each documentation section and generate a markdown file for each function.\r\n  * script could also generate a subsection of index for generated functions (that goes into SUMMARY.md)\r\n\r\nComments welcome"},"comment":{"url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/comments/154825507","html_url":"https://github.com/opentx/lua-reference-guide/issues/7#issuecomment-154825507","issue_url":"https://api.github.com/repos/opentx/lua-reference-guide/issues/7","id":154825507,"user":{"login":"dsbeach","id":9529475,"avatar_url":"https://avatars.githubusercontent.com/u/9529475?v=3","gravatar_id":"","url":"https://api.github.com/users/dsbeach","html_url":"https://github.com/dsbeach","followers_url":"https://api.github.com/users/dsbeach/followers","following_url":"https://api.github.com/users/dsbeach/following{/other_user}","gists_url":"https://api.github.com/users/dsbeach/gists{/gist_id}","starred_url":"https://api.github.com/users/dsbeach/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dsbeach/subscriptions","organizations_url":"https://api.github.com/users/dsbeach/orgs","repos_url":"https://api.github.com/users/dsbeach/repos","events_url":"https://api.github.com/users/dsbeach/events{/privacy}","received_events_url":"https://api.github.com/users/dsbeach/received_events","type":"User","site_admin":false},"created_at":"2015-11-08T13:04:10Z","updated_at":"2015-11-08T13:04:10Z","body":"I like the idea and the consistent formatting.  However, I'm wondering if there might be a way to enhance this approach to include an example script and sample output.\r\n\r\nLook at https://opentx.gitbooks.io/opentx-lua-reference-guide/content/gettime.html\r\n\r\nCould the python script detect the existence of  \"gettime.lua\" and/or \"gettime.png\" (ideally in the book's git repository) and generate the appropriate markdown?\r\n\r\nI think examples have a lot of value, and would appreciate their inclusion."}}