{"action":"created","issue":{"url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/3186","labels_url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/3186/labels{/name}","comments_url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/3186/comments","events_url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/3186/events","html_url":"https://github.com/linuxmint/Cinnamon/issues/3186","id":34261591,"number":3186,"title":"Better documentation of the Cinnamon API","user":{"login":"theSeppi","id":5564491,"avatar_url":"https://avatars.githubusercontent.com/u/5564491?v=3","gravatar_id":"","url":"https://api.github.com/users/theSeppi","html_url":"https://github.com/theSeppi","followers_url":"https://api.github.com/users/theSeppi/followers","following_url":"https://api.github.com/users/theSeppi/following{/other_user}","gists_url":"https://api.github.com/users/theSeppi/gists{/gist_id}","starred_url":"https://api.github.com/users/theSeppi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/theSeppi/subscriptions","organizations_url":"https://api.github.com/users/theSeppi/orgs","repos_url":"https://api.github.com/users/theSeppi/repos","events_url":"https://api.github.com/users/theSeppi/events{/privacy}","received_events_url":"https://api.github.com/users/theSeppi/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/linuxmint/Cinnamon/labels/FEATURE%20REQUEST","name":"FEATURE REQUEST","color":"02e10c"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":15,"created_at":"2014-05-25T12:09:30Z","updated_at":"2015-05-20T07:50:54Z","closed_at":null,"body":"A thing I hate about Cinnamon (as a fairly unexerienced developer in this area) is the lack of an API documentation.\r\n\r\nEven the most simple applet becomes hard to create - The only thing I could find was the Force Quit/xkill applet tutorial.\r\n\r\nI think this is quite a sad fact, because Cinnamon is continuosly gaining popularity. With such a growing community comes a greater amount of developers.\r\n\r\nJavaScript itself is easy to learn, but where am I supposed to learn the Cinnamon-specific stuff? Of course I can try to understand the commands and classes from the given applets, but so I will never learn what every specific command exactly does and I will certainly never know what commands exist.\r\n\r\nSo I think a complete API documentation for Applets, Desklets and Extensions is crucial for Cinnamon.\r\n\r\n***\r\nI already filed this at community.linuxmint.com, and they asked me to write this here"},"comment":{"url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/comments/103799658","html_url":"https://github.com/linuxmint/Cinnamon/issues/3186#issuecomment-103799658","issue_url":"https://api.github.com/repos/linuxmint/Cinnamon/issues/3186","id":103799658,"user":{"login":"dalcde","id":1336336,"avatar_url":"https://avatars.githubusercontent.com/u/1336336?v=3","gravatar_id":"","url":"https://api.github.com/users/dalcde","html_url":"https://github.com/dalcde","followers_url":"https://api.github.com/users/dalcde/followers","following_url":"https://api.github.com/users/dalcde/following{/other_user}","gists_url":"https://api.github.com/users/dalcde/gists{/gist_id}","starred_url":"https://api.github.com/users/dalcde/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dalcde/subscriptions","organizations_url":"https://api.github.com/users/dalcde/orgs","repos_url":"https://api.github.com/users/dalcde/repos","events_url":"https://api.github.com/users/dalcde/events{/privacy}","received_events_url":"https://api.github.com/users/dalcde/received_events","type":"User","site_admin":false},"created_at":"2015-05-20T07:50:54Z","updated_at":"2015-05-20T07:50:54Z","body":"For those interested in contributing to documentation and tutorials, here are the guidelines regarding how to document code and write tutorials under the current system:\r\n\r\nhttp://dec41.user.srcf.net/cinnadoc/cinnamon-js/documenting-source.html\r\nhttp://dec41.user.srcf.net/cinnadoc/cinnamon-js/documenting-tutorial.html\r\n\r\nCode documentation is written inside the code itself with comment blocks, while tutorials are separate .xml files. Currently, all tutorials have to be written in docbook format, which is a bit like html but the tag names are longer.\r\n\r\n*NOTE to self: write a docbook crash-course tutorial*\r\n\r\nIf you don't wish to learn the devious docbook format, there are certain online converters from other languages to docbook, eg. https://foliovision.com/seo-tools/pandoc-online. However, conversion from Markdown is usually not very successful. I suppose more structured formats such as LaTeX will produce better output, but I haven't tried. Regardless, there will always be some need of fine-tuning the sectioning and layering to fit into the general structure.\r\n\r\nIf anyone writes some tutorial in non-docbook format, I wouldn't mind help converting them to docbook afterwards. After all, it is easier to do the conversion than write one myself :) However, if you plan to write a non-trivial amount of tutorials, it would be a good idea to learn the docbook format."}}