{"action":"created","issue":{"url":"https://api.github.com/repos/minetest/minetest/issues/7084","repository_url":"https://api.github.com/repos/minetest/minetest","labels_url":"https://api.github.com/repos/minetest/minetest/issues/7084/labels{/name}","comments_url":"https://api.github.com/repos/minetest/minetest/issues/7084/comments","events_url":"https://api.github.com/repos/minetest/minetest/issues/7084/events","html_url":"https://github.com/minetest/minetest/issues/7084","id":301056660,"number":7084,"title":"Consolidate API documentation","user":{"login":"tacotexmex","id":25328789,"avatar_url":"https://avatars3.githubusercontent.com/u/25328789?v=4","gravatar_id":"","url":"https://api.github.com/users/tacotexmex","html_url":"https://github.com/tacotexmex","followers_url":"https://api.github.com/users/tacotexmex/followers","following_url":"https://api.github.com/users/tacotexmex/following{/other_user}","gists_url":"https://api.github.com/users/tacotexmex/gists{/gist_id}","starred_url":"https://api.github.com/users/tacotexmex/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tacotexmex/subscriptions","organizations_url":"https://api.github.com/users/tacotexmex/orgs","repos_url":"https://api.github.com/users/tacotexmex/repos","events_url":"https://api.github.com/users/tacotexmex/events{/privacy}","received_events_url":"https://api.github.com/users/tacotexmex/received_events","type":"User","site_admin":false},"labels":[{"id":73369122,"url":"https://api.github.com/repos/minetest/minetest/labels/@%20Documentation","name":"@ Documentation","color":"0e8a16","default":false},{"id":285897422,"url":"https://api.github.com/repos/minetest/minetest/labels/Request%20/%20Suggestion","name":"Request / Suggestion","color":"8db4e0","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":58,"created_at":"2018-02-28T15:00:46Z","updated_at":"2018-03-23T15:04:05Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"##### Issue type\r\n - Documentation issue\r\n\r\n## Summary\r\nlua_api.txt is quite messy. Wiki is constantly out of date. (Show of hands all who still _love_ working with MediaWiki 😉 )\r\n\r\nWhat about a consolidation of the API documentation to a single source of truth, served as a **automatically generated rich static web page that's actually legible**?\r\n\r\nThere are many generators, [Slate](https://lord.github.io/slate/) is one of them.\r\n\r\n### Pros\r\n- Legible design\r\n- Everything on a single page (avid Ctrl+F:ing lua_api.txt users would still feel at home)\r\n- Slate is just Markdown (lua_api.txt is Markdown too, at least to a large degree)\r\n- Out-of-the-box syntax highlighting\r\n- Still hosted on Github (workflow won't have to change much)\r\n\r\n### Cons\r\n- Some reorganizing of lua_api.txt probably needed\r\n- If hosted in a separate repo, separate PR needed (so let's not)\r\n- Arbitrary argument about the modern web, specific style or overhead\r\n\r\n### Quick FAQ\r\n- **Slate is ugly/wrong language/wrong license**\r\n  - Let's be clear that Slate is _only one example_ out of many.\r\n- **Why don't you just do it yourself?**\r\n  - I could, but if people pushed updates to lua_api.txt the old way it'd get outdated before I could say mese. (the wiki problem)\r\n- **I like it the way it is, real developers should read text files anyway**\r\n  - Good for you, but what about aspiring ones? Let's lower the bar, because everybody likes legible documentation."},"comment":{"url":"https://api.github.com/repos/minetest/minetest/issues/comments/375694686","html_url":"https://github.com/minetest/minetest/issues/7084#issuecomment-375694686","issue_url":"https://api.github.com/repos/minetest/minetest/issues/7084","id":375694686,"user":{"login":"tacotexmex","id":25328789,"avatar_url":"https://avatars3.githubusercontent.com/u/25328789?v=4","gravatar_id":"","url":"https://api.github.com/users/tacotexmex","html_url":"https://github.com/tacotexmex","followers_url":"https://api.github.com/users/tacotexmex/followers","following_url":"https://api.github.com/users/tacotexmex/following{/other_user}","gists_url":"https://api.github.com/users/tacotexmex/gists{/gist_id}","starred_url":"https://api.github.com/users/tacotexmex/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tacotexmex/subscriptions","organizations_url":"https://api.github.com/users/tacotexmex/orgs","repos_url":"https://api.github.com/users/tacotexmex/repos","events_url":"https://api.github.com/users/tacotexmex/events{/privacy}","received_events_url":"https://api.github.com/users/tacotexmex/received_events","type":"User","site_admin":false},"created_at":"2018-03-23T15:04:05Z","updated_at":"2018-03-23T15:04:05Z","author_association":"CONTRIBUTOR","body":"Good work @pauloue. Now that we know that we can have completely automatic builds of lua_api.txt, we need to decide if Slate is viable. @rubenwardy had issues with search for example.\r\n\r\nSpeaking of Read the Docs I saw that it supports versioning, internationalization and multiple export formats (including PDFs)."}}
{"actor":{"display_login":"tacotexmex"}}