{"action":"created","issue":{"url":"https://api.github.com/repos/sherpa/sherpa/issues/197","repository_url":"https://api.github.com/repos/sherpa/sherpa","labels_url":"https://api.github.com/repos/sherpa/sherpa/issues/197/labels{/name}","comments_url":"https://api.github.com/repos/sherpa/sherpa/issues/197/comments","events_url":"https://api.github.com/repos/sherpa/sherpa/issues/197/events","html_url":"https://github.com/sherpa/sherpa/issues/197","id":143478066,"number":197,"title":"Adding Sphinx documentation","user":{"login":"DougBurke","id":224638,"avatar_url":"https://avatars.githubusercontent.com/u/224638?v=3","gravatar_id":"","url":"https://api.github.com/users/DougBurke","html_url":"https://github.com/DougBurke","followers_url":"https://api.github.com/users/DougBurke/followers","following_url":"https://api.github.com/users/DougBurke/following{/other_user}","gists_url":"https://api.github.com/users/DougBurke/gists{/gist_id}","starred_url":"https://api.github.com/users/DougBurke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DougBurke/subscriptions","organizations_url":"https://api.github.com/users/DougBurke/orgs","repos_url":"https://api.github.com/users/DougBurke/repos","events_url":"https://api.github.com/users/DougBurke/events{/privacy}","received_events_url":"https://api.github.com/users/DougBurke/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/sherpa/sherpa/labels/area:docs","name":"area:docs","color":"d4c5f9"},{"url":"https://api.github.com/repos/sherpa/sherpa/labels/type:enhancement","name":"type:enhancement","color":"fbca04"}],"state":"open","locked":false,"assignee":{"login":"DougBurke","id":224638,"avatar_url":"https://avatars.githubusercontent.com/u/224638?v=3","gravatar_id":"","url":"https://api.github.com/users/DougBurke","html_url":"https://github.com/DougBurke","followers_url":"https://api.github.com/users/DougBurke/followers","following_url":"https://api.github.com/users/DougBurke/following{/other_user}","gists_url":"https://api.github.com/users/DougBurke/gists{/gist_id}","starred_url":"https://api.github.com/users/DougBurke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DougBurke/subscriptions","organizations_url":"https://api.github.com/users/DougBurke/orgs","repos_url":"https://api.github.com/users/DougBurke/repos","events_url":"https://api.github.com/users/DougBurke/events{/privacy}","received_events_url":"https://api.github.com/users/DougBurke/received_events","type":"User","site_admin":false},"milestone":null,"comments":28,"created_at":"2016-03-25T11:04:19Z","updated_at":"2016-05-05T13:52:40Z","closed_at":null,"body":"As I know there's been discussion about this at [PyAstro16](http://python-in-astronomy.github.io/2016/), I thought it worth mentioning what I've learnt in my investigations to help anyone who wants to work on this. Please do!\r\n\r\nThere is a branch at [feature/sphinx-docs](/sherpa/sherpa/tree/feature/sphinx-docs/) which shows what I've done. I have a version on read-the-docs: [output](http://sherpa.readthedocs.org/en/latest/) and [configuration information](https://readthedocs.org/projects/sherpa/).\r\n\r\nFrom memory, the issues include (they are *not* ordered in severity, can overlap somewhat, and may actually feed into other possible improvements we could do):\r\n\r\n- Move the contents of the existing `doc/` directory somewhere else (e.g. `notebook/`) so that `doc/` can be used for Sphinx.\r\n\r\n- I had trouble getting Sherpa to build on Read The Docs as soon as I tried getting it to run code (e.g. to make sure the screen output is up to date); I forget the details but the [last log](https://readthedocs.org/projects/sherpa/builds/3261030/) suggests I gave up as soon as it complained about missing `yacc`. My thoughts at the time are that the build would have to be done locally, with the results pushed to the web site, but I didn't investigate this any further. There have been a number of build improvements to Sherpa since then, but we still need to compile code.\r\n\r\n- I needed to add a customized IPython directive to grab the output from the Sherpa logger and include it into the Sphinx shell. It's pretty basic, but to save time re-inventing the wheel you can find it at  676cd6f77b5386d82065dd64439061bc1527a30a. If you don't do this then a lot of screen output is not included in the HTML output, which defeats the purpose just a little bit ;-)\r\n\r\n- The presence of optional/multiple code paths is a challenge, both for building (what is included and what isn't) and actual documentation text: for example how to best explain functionality that may only be present in one I/O backend. This is a combination of issues: technological, documentation content, and social (what do we want).\r\n\r\n- If you auto-generate the module layout then you end up with a confusing mess. Many Sherpa modules re-export content from other modules, which leads to a lot of repeated information and some very-large modules (e.g. `sherpa.astro.ui`), both of which lead to reader confusion and fatigue. If you don't autogenerate the layout, then you have a lot of work ahead of you, and you are still likely to hit some of these problems.\r\n\r\n- There has been some clean up of the code since I worked on this, removing unused and CIAO-specific code, but there are probably still files left over that need to be excluded from the auto-generated documentation. Also, some of the modules are too large (I know I've already mentioned this, but it needs repeating).\r\n\r\n- I am fairly sure some of the \"clever\" wrapping we do, to make some functionality easier to use from IPython, interacts poorly with Python docstrings, and hence the generated documentation. As an example, we allow users to say `sherpa.astro.ui.set_source(sherpa.astro.ui.polynom1d.cpt)` but `sherpa.astro.ui.polynom1d` is actually a `sherpa.ui.utils.ModelWrapper` instance around the `sherpa.models.basic.Polynom1D` class, which is where the docstrings should be (but currently are). Also, `Polynom1D` is also available as `sherpa.models.Polynom1D` (just re-iterating the point about repeated documentation). We (@olaurino and I) have talked about this particular issue before (i.e. pass through the model docstring) but that hasn't been worked on (and the use case of making sure that the information is available to Sphinx wasn't thought of).\r\n\r\n- I think we have good coverage of the UI API (although some is still missing and the content can be improved), except for a few specific areas such as the model instances and functions written in C, but the documentation of the lower-level routines is in a sorry state. Work on Sphinx documentation should help illuminate what areas need work, and can be done outside of this project (I have been trying to add stuff as I work on code fixes and improvements, in particular the C functions, but lots more to be done).\r\n\r\n- See also my [comment on #22](https://github.com/sherpa/sherpa/issues/22#issuecomment-104009145) which discusses a problem I had with the DS9-related code when running Sphinx\r\n[**note added 16:25 EDT Friday 25 March 2016**]\r\n\r\n- One suggestion that has been made is to not include the session-based API (what is referred to as the UI layer above - i.e. `sherpa.astro.ui` and `sherpa.ui`) in the Sphinx documentation. This would essentially have the UI layer documented as part of CIAO and the object-oriented API (which needs a lot of documentation) for the Sphinx documentation.\r\n[**note added 14:48 EDT Tuesday 26 April 2016**]"},"comment":{"url":"https://api.github.com/repos/sherpa/sherpa/issues/comments/217159720","html_url":"https://github.com/sherpa/sherpa/issues/197#issuecomment-217159720","issue_url":"https://api.github.com/repos/sherpa/sherpa/issues/197","id":217159720,"user":{"login":"DougBurke","id":224638,"avatar_url":"https://avatars.githubusercontent.com/u/224638?v=3","gravatar_id":"","url":"https://api.github.com/users/DougBurke","html_url":"https://github.com/DougBurke","followers_url":"https://api.github.com/users/DougBurke/followers","following_url":"https://api.github.com/users/DougBurke/following{/other_user}","gists_url":"https://api.github.com/users/DougBurke/gists{/gist_id}","starred_url":"https://api.github.com/users/DougBurke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DougBurke/subscriptions","organizations_url":"https://api.github.com/users/DougBurke/orgs","repos_url":"https://api.github.com/users/DougBurke/repos","events_url":"https://api.github.com/users/DougBurke/events{/privacy}","received_events_url":"https://api.github.com/users/DougBurke/received_events","type":"User","site_admin":false},"created_at":"2016-05-05T13:52:40Z","updated_at":"2016-05-05T13:52:40Z","body":"@olaurino - there is a doctest extension which I did play around with, but wasn't sure about how well it worked so have removed it for now. As @taldcroft mentioned, there's trickiness with handling floating-point numbers, especially for our fitting examples where platform and build differences (e.g. exactly which version of numpy or MKL or ... is used) can come into play. This is not to say it shouldn't be done, but it is not my focus at the moment.\r\n\r\n@taldcroft - do you know how the pshinx builds are done in astropy (I don't have the energy to go digging through the CI wrapper code that astropy uses)? I can convert sphinx warnings to errors using the `sphinx_build` command, with the `-W` flag, but this doesn't appear to be exposed to the `build_sphinx` target of `setuptools`. It's a lot easier for me, given our `.travis.yml` setup, to just use `python setup.py build_sphinx`, but perhaps @olaurino can suggest a way to support running `sphinx_build` directly."}}