How to publish these tutorials? about astropy-tutorials

[astrofrog]

As far as I can see, the options are either to incorporate it into the main docs, or start a new repository based on the package template (which will give you the correct docs formatting) and have it build via readthedocs, then have tutorials.astropy.org point to readthedocs. The advantage of merging with the main repo is that the search would work across both, and the advantage of the separate repository is that it can include larger example files that we'd want to keep out of the main repository, so there's no single obvious solution.

[eteq]

I think we don't want to plan on putting these in the main package. Some in the future might end up being small and straightforward enough that we move them, but none of the current ones leap out at me as in that category. Regardless, generally it would be nice to have this remain a space that can have larger or incomplete tutorials that we may never want in the main repo.

For using RTD to build the repo, that makes sense, but I'm not sure the affiliated package template should be used, as that adds a lot of complexity that shouldn't be needed here. It should be fine to just use the affiliated package conf.py and pip-requirements - I don't think anything else is needed because this repo won't have code. I'm happy to set up the sphinx and RTD stuff if need be.

I agree with @astrofrog that it would be good to have the tutorials included in the atropy.org search, though. There must be a way to search across multiple sphinx pages - RTD does that, so it's certainly possible... The question is just how easy it is. (Anyone know how this works? I can try looking into it if not)

[eteq]

Oh, one other possibility for how to do the hosting: it could be done like astropy.org, where we have an upload_docs.py script in the content repo that uploads the generated Sphinx content to a github pages repo. The existing script could be put in this repo (astropy-tutorials) and should be reasonably easy to adapt to this need. The downside of that is that it requires someone to manually push out the web page when it changes - that gives better control over the public content, but makes it more likely someone will forget...

Having said that, I think @astrofrog is right that RTD is probably easier anyway, but I just thought I should mention this for the sake of making the options clear.

[kelle]

this needs to be revisited now that we've decided to use ipython notebooks.

[Cadair]

Myself and @astrofrog were having a bit of an off-the-wall discussion about how awesome it would be if there was no manual input into translating notebooks into website. i.e. a workflow thus:

upload ipynb to GH > navigate to a website, see a rendered version.

The simplest way of doing this would probably be something like using nbviewer. A better way would be writing some awesome python based webscript that automatically translated on-the-fly.

[hamogu]

Another 6 months have gone by and we still don't publish our tutorials (or at least I cannot find them on http://www.astropy.org/astropy-tutorials/ ).
Any progress on this?
Otherwise, I would suggest that we start with a non-ideal, but simple solution: We just add links that allow people to see the awesome tutorials we already have on http://nbviewer.ipython.org/
That can be done in about 10 min of work. Once that is in place, we can still go back and see if we can come up with a better solution.

[jfoster17]

Hi @hamogu, thanks for following up on this. In fact, @adrn has done a really nice job of making an automatic system (see https://github.com/astropy/astropy-tutorials/blob/master/CONTRIBUTING.rst) and we have an open PR #51 for a Quantities tutorial that we plan to make our first official/publicized tutorial.

[eteq]

To add to that, I think the idea is to do an astrobetter post where we do this, and at that time all that's needed to make all the other tutorials visible on the web site is to change their "published" metadata from "false" to "true". (That's why the automatic system isn't including them right now)

[hamogu]

Since that is agreed on, should this github issue be closed?

On 04/16/2014 10:46 PM, Erik Tollerud wrote:

To add to that, I think the idea is to do an astrobetter post where we
do this, and at that time all that's needed to make all the other
tutorials visible on the web site is to change their "published"
metadata from "false" to "true". (That's why the automatic system
isn't including them right now)

—
Reply to this email directly or view it on GitHub
#8 (comment).

[eteq]

That's a very good point, @hamogu ! Closing now.