{"action":"created","issue":{"url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/1015","repository_url":"https://api.github.com/repos/ElektraInitiative/libelektra","labels_url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/1015/labels{/name}","comments_url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/1015/comments","events_url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/1015/events","html_url":"https://github.com/ElektraInitiative/libelektra/issues/1015","id":182044283,"number":1015,"title":"Website structure","user":{"login":"Namoshek","id":8877609,"avatar_url":"https://avatars.githubusercontent.com/u/8877609?v=3","gravatar_id":"","url":"https://api.github.com/users/Namoshek","html_url":"https://github.com/Namoshek","followers_url":"https://api.github.com/users/Namoshek/followers","following_url":"https://api.github.com/users/Namoshek/following{/other_user}","gists_url":"https://api.github.com/users/Namoshek/gists{/gist_id}","starred_url":"https://api.github.com/users/Namoshek/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Namoshek/subscriptions","organizations_url":"https://api.github.com/users/Namoshek/orgs","repos_url":"https://api.github.com/users/Namoshek/repos","events_url":"https://api.github.com/users/Namoshek/events{/privacy}","received_events_url":"https://api.github.com/users/Namoshek/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/ElektraInitiative/libelektra/labels/proposal","name":"proposal","color":"fef2c0"},{"url":"https://api.github.com/repos/ElektraInitiative/libelektra/labels/work%20in%20progress","name":"work in progress","color":"006b75"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":14,"created_at":"2016-10-10T15:28:15Z","updated_at":"2016-10-18T14:45:20Z","closed_at":null,"body":"Suggestions on the structure and design of the new website are needed @ElektraInitiative/elektradevelopers.\r\n\r\nCurrently, there is ...\r\n- a main page without any content.\r\n- a documentation page listing all files of the `doc` directory.\r\n- a tutorial page listing all files of the `doc/tutorials` directory.\r\n- a snippet converter.\r\n\r\nIn my opinion, we definitely need some more things like ...\r\n- news page\r\n- changelog\r\n- link to GitHub\r\n- ... but also a more guided documentation section, so more in-depth suggestions on the documentation structure would be appreatiated as well!\r\n\r\nIt would be nice to hear some opinions about what to put where!\r\n\r\nA live demo of the website can always be found at http://namoshek.at:9000."},"comment":{"url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/comments/254530449","html_url":"https://github.com/ElektraInitiative/libelektra/issues/1015#issuecomment-254530449","issue_url":"https://api.github.com/repos/ElektraInitiative/libelektra/issues/1015","id":254530449,"user":{"login":"markus2330","id":7949075,"avatar_url":"https://avatars.githubusercontent.com/u/7949075?v=3","gravatar_id":"","url":"https://api.github.com/users/markus2330","html_url":"https://github.com/markus2330","followers_url":"https://api.github.com/users/markus2330/followers","following_url":"https://api.github.com/users/markus2330/following{/other_user}","gists_url":"https://api.github.com/users/markus2330/gists{/gist_id}","starred_url":"https://api.github.com/users/markus2330/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/markus2330/subscriptions","organizations_url":"https://api.github.com/users/markus2330/orgs","repos_url":"https://api.github.com/users/markus2330/repos","events_url":"https://api.github.com/users/markus2330/events{/privacy}","received_events_url":"https://api.github.com/users/markus2330/received_events","type":"User","site_admin":false},"created_at":"2016-10-18T14:45:20Z","updated_at":"2016-10-18T14:45:20Z","body":"First off: Yes, the basic structure (\"the static parts\") should be defined by hand.\r\n\r\n>  Take a very minimalistic source file, parse it, make some HTTP calls to github and build a more comprehensive structure file. (Sounds a lot better than it actually is...)\r\n\r\nWhy making HTTP calls during this process? Just iterating over directories and files should be enough.\r\n\r\n> The problem I currently face is the plugin documentation. Parsing the README.md is not going to work within a dynamic context. There are simply too many factors I'd have to consider.\r\n\r\nWhat do you mean with dynamic context? I thought that the script parsing the README.md does so in the repo statically. In the dynamic context (the browser) should then only fetch a single prepared file (without much parsing).\r\n\r\n> Making a static script for it might work, but I don't like this either.\r\n\r\nAs said it is okay to change the README.md to make your live easier.\r\n\r\n> I also ran into the API rate limit while trying around.\r\n\r\nThe solution here would be to \"reimplement\" the parts of the github API we use and use our own API it as fallback whenever github has troubles (e.g. shuts down its API).\r\n\r\n> Somehow I really feel as if a manually maintained structure file would still be our best option. [...] So currently I'm not sure what to do.\r\n\r\nI think a mixture is the best option if you do not want a webpage that is completely statically generated. Let me try to explain again (I will invent some files in `doc/webpage`, the file names are open for discussion). There are two phases:\r\n\r\n## Phase 1: Static context\r\n\r\nThe first phase is crawling the checked out repo and bringing a (also checked-in) file up-to-date. Let us call the script that does that  `assemble-webpage-structure` and the file containing all information needed for \"Phase 2\"  `doc/webpage/structure`.\r\n\r\nFirst there are some basic definitions in `doc/webpage/main` which defines the main menu which is carefully crafted by hand (and static). It contains references to folders and how their entries should be added, for example: \"src/plugins contains a README.md in the format `- []()`, use the entries in this order and use subsections for subfolders\". There are some features like this:\r\n\r\n1. use all sub-folders as menu entries (e.g. src/tools, src/bindings)\r\n2. use all files of a folder as menu entries (e.g. doc/help)\r\n3. use README.md in `^[]()` format, e.g. src/libs/README.md\r\n4.  use README.md in`^- []()` format, where sections define subfolders, e.g. src/plugins/README.md\r\n\r\nThe result of phase 1 is a single file`doc/webpage/structure`  describing the whole structure of the web page and every other metadata you might need in the dynamic context.\r\n\r\nAfter the script `assemble-webpage-structure` is runned, the updated `doc/webpage/structure` needs to be commited.\r\n\r\n## Phase 2: Webpage (Dynamic context)\r\n\r\nThe webpage fetches the `doc/webpage/structure` which contains everything precompiled in a way so that you can easily show the main page and know the structure of the whole webpage.\r\n\r\nThe goal of `doc/webpage/main` (and others) is to be short and maintainable files, the goal of  `doc/webpage/structure` is to be an ideal fit for your needs in the dynamic context. Does that make sense?"}}
{"actor":{"display_login":"markus2330"}}