{"action":"created","issue":{"url":"https://api.github.com/repos/gammapy/gammapy/issues/1168","repository_url":"https://api.github.com/repos/gammapy/gammapy","labels_url":"https://api.github.com/repos/gammapy/gammapy/issues/1168/labels{/name}","comments_url":"https://api.github.com/repos/gammapy/gammapy/issues/1168/comments","events_url":"https://api.github.com/repos/gammapy/gammapy/issues/1168/events","html_url":"https://github.com/gammapy/gammapy/pull/1168","id":266051711,"number":1168,"title":"Move Sphinx-based tutorials to Jupyter notebooks","user":{"login":"cdeil","id":852409,"avatar_url":"https://avatars3.githubusercontent.com/u/852409?v=4","gravatar_id":"","url":"https://api.github.com/users/cdeil","html_url":"https://github.com/cdeil","followers_url":"https://api.github.com/users/cdeil/followers","following_url":"https://api.github.com/users/cdeil/following{/other_user}","gists_url":"https://api.github.com/users/cdeil/gists{/gist_id}","starred_url":"https://api.github.com/users/cdeil/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cdeil/subscriptions","organizations_url":"https://api.github.com/users/cdeil/orgs","repos_url":"https://api.github.com/users/cdeil/repos","events_url":"https://api.github.com/users/cdeil/events{/privacy}","received_events_url":"https://api.github.com/users/cdeil/received_events","type":"User","site_admin":false},"labels":[{"id":81703920,"url":"https://api.github.com/repos/gammapy/gammapy/labels/docs","name":"docs","color":"0052cc","default":false}],"state":"closed","locked":false,"assignee":{"login":"cdeil","id":852409,"avatar_url":"https://avatars3.githubusercontent.com/u/852409?v=4","gravatar_id":"","url":"https://api.github.com/users/cdeil","html_url":"https://github.com/cdeil","followers_url":"https://api.github.com/users/cdeil/followers","following_url":"https://api.github.com/users/cdeil/following{/other_user}","gists_url":"https://api.github.com/users/cdeil/gists{/gist_id}","starred_url":"https://api.github.com/users/cdeil/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cdeil/subscriptions","organizations_url":"https://api.github.com/users/cdeil/orgs","repos_url":"https://api.github.com/users/cdeil/repos","events_url":"https://api.github.com/users/cdeil/events{/privacy}","received_events_url":"https://api.github.com/users/cdeil/received_events","type":"User","site_admin":false},"assignees":[{"login":"cdeil","id":852409,"avatar_url":"https://avatars3.githubusercontent.com/u/852409?v=4","gravatar_id":"","url":"https://api.github.com/users/cdeil","html_url":"https://github.com/cdeil","followers_url":"https://api.github.com/users/cdeil/followers","following_url":"https://api.github.com/users/cdeil/following{/other_user}","gists_url":"https://api.github.com/users/cdeil/gists{/gist_id}","starred_url":"https://api.github.com/users/cdeil/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cdeil/subscriptions","organizations_url":"https://api.github.com/users/cdeil/orgs","repos_url":"https://api.github.com/users/cdeil/repos","events_url":"https://api.github.com/users/cdeil/events{/privacy}","received_events_url":"https://api.github.com/users/cdeil/received_events","type":"User","site_admin":false}],"milestone":{"url":"https://api.github.com/repos/gammapy/gammapy/milestones/10","html_url":"https://github.com/gammapy/gammapy/milestone/10","labels_url":"https://api.github.com/repos/gammapy/gammapy/milestones/10/labels","id":2282173,"number":10,"title":"0.7","description":"","creator":{"login":"cdeil","id":852409,"avatar_url":"https://avatars3.githubusercontent.com/u/852409?v=4","gravatar_id":"","url":"https://api.github.com/users/cdeil","html_url":"https://github.com/cdeil","followers_url":"https://api.github.com/users/cdeil/followers","following_url":"https://api.github.com/users/cdeil/following{/other_user}","gists_url":"https://api.github.com/users/cdeil/gists{/gist_id}","starred_url":"https://api.github.com/users/cdeil/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cdeil/subscriptions","organizations_url":"https://api.github.com/users/cdeil/orgs","repos_url":"https://api.github.com/users/cdeil/repos","events_url":"https://api.github.com/users/cdeil/events{/privacy}","received_events_url":"https://api.github.com/users/cdeil/received_events","type":"User","site_admin":false},"open_issues":82,"closed_issues":136,"state":"open","created_at":"2017-01-27T12:50:29Z","updated_at":"2017-10-19T11:38:38Z","due_on":null,"closed_at":null},"comments":16,"created_at":"2017-10-17T09:22:07Z","updated_at":"2017-10-19T18:54:42Z","closed_at":"2017-10-17T13:29:00Z","author_association":"OWNER","pull_request":{"url":"https://api.github.com/repos/gammapy/gammapy/pulls/1168","html_url":"https://github.com/gammapy/gammapy/pull/1168","diff_url":"https://github.com/gammapy/gammapy/pull/1168.diff","patch_url":"https://github.com/gammapy/gammapy/pull/1168.patch"},"body":"I'd like to propose that we move the Sphinx-based tutorials we have in `docs/tutorials` here:\r\nhttp://docs.gammapy.org/en/v0.6/tutorials/index.html\r\nto Jupyter notebooks in `gammapy-extra/notebooks` (and list them at the end under https://nbviewer.jupyter.org/github/gammapy/gammapy-extra/blob/master/index.ipynb#Extra-topics to make it clear that they are pretty specialised, not the first thing to look at for most users, but also not useless IMO).\r\n\r\nI'm 50:50 on pros and cons of writing and maintaining tutorials in Sphinx or Jupyter notebooks, so @adonath and @joleroi and anyone - please comment what you think!\r\n\r\nThe problem with `docs/tutorials` (apart from being mostly old and not super relevant content for most users) is that it's a second place to put tutorials, and it's hard for users or authors to understand what content is where. And I think with the notebooks, people are mostly happy so we don't want to give that up.\r\n\r\nThere's also the problem that `python setup.py build_docs` is the slowest and most (at least for me) most annoying part of the Gammapy development experience. It currently takes 4 min on my machine, and I'd like to see it get faster, not slower. Currently `docs/tutorials` only takes 20 seconds out of those 4 min, so it's not a big win. But there we were always careful to choose datasets and analyses that run within seconds, whereas in the notebooks it's OK to have an analysis example that takes a bit longer.\r\n\r\nWe will still have to discuss what content should go in per-subpackage docs like http://docs.gammapy.org/en/latest/spectrum/index.html and what content in separate examples and tutorials. For sure the goal is not to remove all examples from the Sphinx docs and to only leave the API docs there. We will keep both, unless really good tooling comes up that allows generating notebooks from Jupyter notebooks which doesn't exist yet. \r\n\r\nBottom line - is this aa step in the right direction for now?"},"comment":{"url":"https://api.github.com/repos/gammapy/gammapy/issues/comments/338003471","html_url":"https://github.com/gammapy/gammapy/pull/1168#issuecomment-338003471","issue_url":"https://api.github.com/repos/gammapy/gammapy/issues/1168","id":338003471,"user":{"login":"Bultako","id":328261,"avatar_url":"https://avatars3.githubusercontent.com/u/328261?v=4","gravatar_id":"","url":"https://api.github.com/users/Bultako","html_url":"https://github.com/Bultako","followers_url":"https://api.github.com/users/Bultako/followers","following_url":"https://api.github.com/users/Bultako/following{/other_user}","gists_url":"https://api.github.com/users/Bultako/gists{/gist_id}","starred_url":"https://api.github.com/users/Bultako/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Bultako/subscriptions","organizations_url":"https://api.github.com/users/Bultako/orgs","repos_url":"https://api.github.com/users/Bultako/repos","events_url":"https://api.github.com/users/Bultako/events{/privacy}","received_events_url":"https://api.github.com/users/Bultako/received_events","type":"User","site_admin":false},"created_at":"2017-10-19T18:54:42Z","updated_at":"2017-10-19T18:54:42Z","author_association":"MEMBER","body":"I have forked a gammapy repo in my GitHub profile, and created a branch `docbuilding-notebooks` https://github.com/Bultako/gammapy/tree/docbuilding-notebooks\r\n\r\nMain modifs are: \r\n* .gitignore to track \r\n       - the generated doc just for your inspection in `docs/_build`folder\r\n       - the *.ipynb files in `docs/folder` (these will be copied from GAMMAPY-EXTRA later on)\r\n* conf.py Sphinx config file in `docs` to make `nbconfig` work nicely\r\n* some *.rst files in `docs`and some *.py files in `gammany`source code folder to replace directive `.. code::` by `..code :: python`and make code inclusion in docs working. You also need to re-install gammany with these new source files.\r\n\r\nRemember you need to install `nbsphinx`:\r\nconda install -c conda-forge nbsphinx\r\n\r\nAnd that's all for the moment.\r\nJust type `python setup.py build-docs` and this mixed interlinked doc of *rst files and notebooks is generated in one shot. We still have some warnings die to orphans *.ipynb files, but this does not prevent their conversion.\r\n\r\nThis is the firs step, still work in progress..\r\n\r\n\r\n"}}
{"actor":{"display_login":"Bultako"}}