{"action":"created","issue":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/9369","repository_url":"https://api.github.com/repos/RIOT-OS/RIOT","labels_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/9369/labels{/name}","comments_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/9369/comments","events_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/9369/events","html_url":"https://github.com/RIOT-OS/RIOT/pull/9369","id":333342091,"node_id":"MDExOlB1bGxSZXF1ZXN0MTk1NTc5MTYx","number":9369,"title":"[WIP] doc: Use Sphinx for documentation.","user":{"login":"jcarrano","id":3057851,"node_id":"MDQ6VXNlcjMwNTc4NTE=","avatar_url":"https://avatars0.githubusercontent.com/u/3057851?v=4","gravatar_id":"","url":"https://api.github.com/users/jcarrano","html_url":"https://github.com/jcarrano","followers_url":"https://api.github.com/users/jcarrano/followers","following_url":"https://api.github.com/users/jcarrano/following{/other_user}","gists_url":"https://api.github.com/users/jcarrano/gists{/gist_id}","starred_url":"https://api.github.com/users/jcarrano/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jcarrano/subscriptions","organizations_url":"https://api.github.com/users/jcarrano/orgs","repos_url":"https://api.github.com/users/jcarrano/repos","events_url":"https://api.github.com/users/jcarrano/events{/privacy}","received_events_url":"https://api.github.com/users/jcarrano/received_events","type":"User","site_admin":false},"labels":[{"id":87985768,"node_id":"MDU6TGFiZWw4Nzk4NTc2OA==","url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/WIP","name":"WIP","color":"009800","default":false},{"id":89327795,"node_id":"MDU6TGFiZWw4OTMyNzc5NQ==","url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/documentation","name":"documentation","color":"f7c6c7","default":false},{"id":104178887,"node_id":"MDU6TGFiZWwxMDQxNzg4ODc=","url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/major","name":"major","color":"ff0000","default":false},{"id":97458574,"node_id":"MDU6TGFiZWw5NzQ1ODU3NA==","url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/new%20feature","name":"new feature","color":"e11d21","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":12,"created_at":"2018-06-18T16:21:47Z","updated_at":"2018-07-09T08:55:06Z","closed_at":null,"author_association":"CONTRIBUTOR","pull_request":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/pulls/9369","html_url":"https://github.com/RIOT-OS/RIOT/pull/9369","diff_url":"https://github.com/RIOT-OS/RIOT/pull/9369.diff","patch_url":"https://github.com/RIOT-OS/RIOT/pull/9369.patch"},"body":"## Documentation in RIOT\r\n\r\nRight now, RIOT is (partly) documented using Doxygen. While it is a great tool, it has its limitations. The main problem with Doxygen is that it is a tool designed for API reference. Documentation is much more than API reference. Ideally we would want to have a \"RIOT handbook\" that walks the user through the different parts of the system, and guides the developer who wants to improve RIOT, alongside the API reference.\r\n\r\nDoxygen does an excellent job at capturing and extracting the low-level details, but has no support for higher-level concepts (like modules, packages or custom constructs). It does not have the flexibility to support them either. In general, it is very oriented towards documenting files and C++ (or C, or Java) constructs. For C the problem is worse because several concepts which are used in practice (like objects and interfaces) do not have a formal representation in thus language and are thus hard to document.\r\n\r\nRegarding the flexibility of doxygen: it is not easy to customize the output. The HTML output does not (easily) support full text search. The only way to organize the docs is with groups, whose meaning is not very well defined, and one ends up with the same entity appearing in multiple pages.\r\n\r\nLast, if a modules has really good documentation, it will probably be too much to have it as a comment in a header file.\r\n\r\n## [Sphinx](http://www.sphinx-doc.org/)\r\n\r\nCheck out the preview here: https://riot-os.readthedocs.io/ . It's still missing everything.\r\n\r\n### Benefits\r\n\r\n* Full text search\r\n* Customizable and themeable output\r\n* Support for automatic documentation using Doxygen and [Breathe](http://breathe.readthedocs.io/).\r\n* Support for custom [\"domains\"](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html). We could define a RIOT domain whose roles are, for example \"package\", \"module\", \"board\", etc. \r\n* If necessary, we can make our own extensions.\r\n* We can publish on [Read the Docs](https://readthedocs.org/).\r\n* We can structure the docs like we want.\r\n* Supports markdown, so we don't need to rewrite what we have. There are [reasons](http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/) for writing new docs in reStructuredText, though.\r\n\r\n### Downsides\r\n\r\n* Requires a more manual involvement for writing and organizing the docs.\r\n* The build process is slower an more complex.\r\n* The integration between Doxygen and Sphinx is not perfect.\r\n* It is more noticeable if we are missing something (maybe this is good). Doxygen, in contrast, is specially good at extracting loads of content.\r\n\r\n### Example\r\n\r\nThe Zephyr project is using Sphinx+Breathe+Doxygen. Check it out [here](http://docs.zephyrproject.org/index.html).\r\n\r\n### Procedure\r\n\r\n1. Doxygen generates XML output.\r\n2. `breathe-apidoc` reads the XML and generates reStructuredText documents with indices (e.g. `doxygenclass` directives)\r\n3. Sphinx (with the breathe extension) reads hand written MD and RST documents, plus the ones generated in step 2. When a `doxygen*` directive is found, the XML database is read and the appropriate document nodes are generated.  \r\n\r\n## TODO\r\n\r\n- [x] Publish a preview of the Sphinx docs.\r\n- [ ] Sketch an outline for the Docs\r\n- [ ] Make the process automatic: There is still not a single makefile controlling everything.\r\n- [ ] Remove conflicting definitions: Doxygen does not like the same entity defined more than once. This happens a lot in board support code. Solution: we can create \"fake\" interfaces, and \"fake\" implementations, so we get some sort of namespacing.\r\n- [ ] Customize breathe-apidoc: The indices it generates are not very detailed.\r\n- [ ] Extract huge comment blocks into their own documents (for example, sock)\r\n- [ ] Create a RIOT hierarchy.\r\n- [ ] Migrate some documents from the wiki.\r\n- [ ] Reduce build times: it takes ages now. I believe it's because `breathe-apidoc` places definitions in multiple places.\r\n\r\n### Further enhancements\r\n\r\n- [ ] Configure [extlinks](http://www.sphinx-doc.org/en/master/ext/extlinks.html) to easily refer to PRs and issues.\r\n- [ ] Add RIOT specific domain. This would provide a \"standard\" way of documenting packages, boards, etc.\r\n- [ ] Make a prettier changelog (there are other project to steal scripts from)\r\n\r\n## Related PRs\r\n\r\nAlternative to: #8516 "},"comment":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/comments/403408533","html_url":"https://github.com/RIOT-OS/RIOT/pull/9369#issuecomment-403408533","issue_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/9369","id":403408533,"node_id":"MDEyOklzc3VlQ29tbWVudDQwMzQwODUzMw==","user":{"login":"jia200x","id":1260616,"node_id":"MDQ6VXNlcjEyNjA2MTY=","avatar_url":"https://avatars3.githubusercontent.com/u/1260616?v=4","gravatar_id":"","url":"https://api.github.com/users/jia200x","html_url":"https://github.com/jia200x","followers_url":"https://api.github.com/users/jia200x/followers","following_url":"https://api.github.com/users/jia200x/following{/other_user}","gists_url":"https://api.github.com/users/jia200x/gists{/gist_id}","starred_url":"https://api.github.com/users/jia200x/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jia200x/subscriptions","organizations_url":"https://api.github.com/users/jia200x/orgs","repos_url":"https://api.github.com/users/jia200x/repos","events_url":"https://api.github.com/users/jia200x/events{/privacy}","received_events_url":"https://api.github.com/users/jia200x/received_events","type":"User","site_admin":false},"created_at":"2018-07-09T08:55:05Z","updated_at":"2018-07-09T08:55:05Z","author_association":"MEMBER","body":"hi @jcarrano,\r\n\r\nAs far as I see, these PR still depends on #8516 because the board documentation is there. Am I right?"}}
{"actor":{"display_login":"jia200x"}}