Major reorganization of top level doc page - #6051

Fix #6043

While I agree with the sentiment in #6043, I think the page you deleted gives very useful information for a beginner on the basics of how to import astropy. You can't really get started with astropy until you know how to import the packages. It is also useful in the sense of providing a community standard for imports (e.g. from astropy import units as u). Also, I just learned something new, about the handy find_api_page function!

I think the page is too focused just in importing. For a beginner, why would they import? What's next? It also includes mentions of classes which are definitely not a "beginner" concept.

I agree that this information is useful but not branded as "getting started". I couldn't find another logical home for it.

I think the information about import conventions is best conveyed via the tutorials.

If you want to make a new page for the command line tools, I could see have that being useful even though I'm still
not sure where it should go in the doc organization.

There is some duplication between the overview and http://www.astropy.org/about.html, but in fact about 2/3 of what is in the overview is not in the astropy.org About page (namely info about astropy core and affiliated packages). Granted, if you look for it you will see the menu bar tab for Affiliated packages, but this has been one of my complaints that Affiliated packages are easily missed.

The other issue I have is that I think the astropy core package Overview page should not link outside of the sphinx docs site to the Astropy Project about page. For some other topics (e.g. tutorials or contributing) it seems OK, but I do find it somewhat jarring to get taken outside of the sphinx doc pages to the Astropy Project pages (look and feel, and loss of navigation). Despite the significant overlap these are different things.

I think it is very important to leave the existing Reporting Issues section in the prominent place it now holds. That is a very fundamental part of our process and the Astropy Project docs don't cover this in sufficient detail.

👍 on killing the Contributing section.

We are working in parallel on updating the astropy.org webpages. The idea is to copy and paste things from Overview into About.

While I agree that navigating between the two sites is awkward, having the information duplicated is worse. Since the Overview/About is not version dependent, I don't see any reason for it live on readthedocs.

The details about "reporting Issues" can be added to "contributing" since it's a way to report problems rather than asking for help.

For a beginner, why would they import?

You know this, but to use any sub-package you need to import it. So the very first thing you need to know to use astropy is how to get the correct symbols into your code. I do remember when import seemed magic and odd. But I agree without some followup it is a little empty!

I think that the answer is doing something slightly more difficult: expand the Getting Started to include a handful of the most basic examples (drawn from the getting started sections for key subpackages), and intertwine that with the existing best practices information. So basically fix #6043 by making a real astropy package Getting Started.

It might also be worth making a top-hits list of links to sub-package Getting Started sections. I.e. FITS, Coordinates, Units and Quantity, Table, Time, ASCII.

I don't know a good place for the command line utilities, but this seems like not-the-worst place.

Oh and re: the import section... I agree with @taldcroft this "narrative" form should be somewhere. While I agree that many users will jump straight into tutorials, some do read (or at least skim) these sorts of guides. If there's a tutorial/example actually titled "basics of how to use astropy and import subpackages and modules", then its fine to drop this page... but I think this does need to be stated very clearly somewhere so that it's clear there is an accepted practice.

It might be the best solution is to change the doc to "How to import astropy" or something like that?

I don't know if I am representative, but I view the sphinx docs as my world for the core astropy and very rarely visit astropy.org. I think that a contributor and user of astropy should be able to find everything they need about core astropy on the sphinx docs. For me jumping out of the sphinx docs is worse than a little duplication, particularly for relatively static information that doesn't get out of sync. Maybe that's just my OCD at the font and style suddenly changing for no obvious reason.

I do think it is fair enough to excise some of the Astropy Project stuff from the core package docs.

But at the same time we should understand the mission of astropy.org. Is it about the Astropy Project, in which the astropy core is the binding centerpiece for a community of packages? Or is it just a shinier gateway to astropy core?

For instance I think the astropy.org landing page should have Affiliated Packages as the second section right after "Install Astropy", where it talks about all the exciting community projects out there that use astropy. Then we might make the site overall a bit more agnostic about core astropy, e.g. don't assume that all issues are going to be reported to github.com/astropy/astropy. If someone has an astropy core issue, then go to the astropy core docs and find out what to do. But if they have a astroquery issue it will be a different story.

@taldcroft - I see your point here... But I think where @kelle is coming from is that most "novice" to intermediate users don't know the difference between "core package" and "Project". So they just see the landing page as the whole thing. They don't really know (nor care) what the difference is between the "docs", the tutorials, and the front page.

(again, though, I think it might help a lot to see what actually ends up on astropy.org after this change... that would make it a bit easier to see the whole picture)

made lots of changes to address all above comments. Pls re-review.

Also see astropy/astropy.github.com#159 for corresponding changes on astropy.org.

My 2 cents, mostly in phase with @taldcroft (agreed on all of #6051 (comment)) :

• The distinction between astropy.org and the sphinx docs could be clarified. It would make more sense for me to have astropy.org focused on the Astropy organisation with affiliated projects etc., and everything about the Astropy package in the sphinx docs. The astropy.org home page with installation instruction was relevant at the beginning of the project, but now it should be something presenting the project, the main package and the affiliated ones (more or less the About page, probably without Citation which could be in a separate page, and with the Affiliated Packages section from the sphinx doc Overview page). Installation is already well described in the sphinx docs (and in the docs of every affiliated package).

• When I discover a new Python package and want to know if this package could be useful for my need, I usually read quickly its doc to get an idea of its features, and for this a few points are important:

  • A few paragraphs describing the goals and main features at the very beginning of the docs. For this I would put most of the Overview page at the beginning of the docs index. And a sentence + link to astropy.org (which is not easy to find currently from the docs).
  • A Quick start page. Almost every project has one, and I usually find this very useful to have an idea of the features and API. The current "Getting Started" page could be developed with some examples of the main features. It must not be too long, to be readable quickly and avoid duplicate content with tutorials or sub-packages index.
  • Then, it's useful to have more detailed tutorials on more specific subjects or sub-packages, or the example gallery, especially for big packages like Astropy.

The purpose of me making these changes is to ease the entry into Python and astropy for novices. I want to expose examples and the tutorials for those who are not quite sure what astropy even does. As a result, I am not as concerned with highlighting the differences between astropy and affiliate packages.

While the installation instructions on sphinx are extensive, they are very intimidating. A "pretty" set of instructions saying just use Anaconda is very important.

While the idea of a Quick Start Guide is a good one, I don't think it's feasible. The expanse of functionality is too wide and the needs of our new users too disparate. I think the our time is better spent on adding more and improving the example gallery and tutorials.

Before and after image:

@kelle - this is looking very good! I like the "after" image. I'd even go one step further and also move "installation" to the user documentation section (maybe making a new, 3-item subsection of "Installing and importing astropy and its subpackages").

One comment only, on installation: For novice linux users, the recommendation really should be to use their package manager: on both Debian and RedHat, astropy is kept up to date very well, and the package manager will take care of dependencies and updates. (I know for Mac and Windows, there is no real choice but to use anaconda, but really, that is not particularly easy.)

One comment only, on installation: For novice linux users, the recommendation really should be to use their package manager

I respectfully disagree, and really think that for novices there should be one and only one recommendation: use Anaconda. That works extremely well for all users regardless of platform and system privileges, and (importantly) does not then have novices mucking about with their system Python. Also, Debian and RedHat are just two flavors, but many linux users may be using something else or some version of enterprise linux that does not keep up to date. (E.g. at my institution it was only a couple of years ago that Python 2.7 became the default. Forget about Python 3!).

To that end, in the installation instructions I think that the Anaconda section should be first and pip should be second.

For example:

Installing astropy

There are a number of options for installing the astropy package which we cover here. For many users, especially novices, the easiest and most common way to install both Python and astropy is with the Anaconda Python distribution.

Anaconda Python distribution

Anaconda is an easy to use distribution that provides Python and a deep set of scientific Python packages, including astropy, numpy, scipy, matplotlib, pandas, and over 700 other packages. It is available for linux, Mac OS, and Windows. Installing Anaconda can be done in minutes and does not require system privileges. Once installed, you can update to the latest version of astropy with:

Would be worth checking for lower-case "python" everywhere. The "Python" language is spelled with a capital P.

It looks like we lost the Example Gallery?

I think the Importing astropy and subpackages page can just be one bullet under Getting Started, and there is no need for a separate "Getting started with subpackages" bullet link to that subsection. This really is a getting started sort of topic, in the sense that an astropy user would only read this once or twice and would not come back to it over and over (like the other docs).

@kelle - looking good now (with comments), thanks!

@mhvk - Re linux installation: I agree with @taldcroft on it. If we talk about novice users, I think it's likely that they don't have root access to their system otherwise they would already been experienced enough to look for the package on pip, etc.

I'm thinking of novice users with a laptop -- those obviously can install any package they want, and using their package manager is substantially simpler than setting up anaconda and keeping it up to date.

Of course, if they are in a department and their computer is run for them, they should just ask their system manager (which should be recommended over anaconda, if only so that astropy is something that gets installed by default for people).

One very important fact about beginner-documentation: Don't show the not recommended uses even for educational purposes. The big DON'T DO THIS is soon forgotten and all they remember is that there is an approach how one can easily import stuff (i.e. from numpy import * or from astropy.units import *).

@MSeifert04 , that is also good advice in parenting. The more you know!

One very important fact about beginner-documentation: Don't show the not recommended uses even for educational purposes.

Sorry, disagree strongly for this particular case. Most beginners will have seen this idiom somewhere along the way (and in fact will see it in many astropy __init_ modules). Sticking your head in the sand and refusing to mention it explicitly is not helpful.

I just pushed two things to @kelle's branch

• The minor line length/header changes that @mhvk requested.
• The rearrangment I had commented on -- @kelle, if you object to this please speak up and I'll revert it.

With these changes can we merge? I don't think we'll resolve the discussion about whether to include the from astropy import * example here, and agree we can open a separate issue about installation.

If this is good I can try to do the rebase to resolve the conflict on Friday.

I believe that most of @eteq's concerns have been addressed.

yes, it's not worth stalling this PR because of the import * stuff. 👍

Thanks for making the small changes, @mwcraig. As I quite strongly feel that one should not leave unlinked material around -- for bit-rot will set in -- I deleted the contents of overview.rst and getting_started.rst. (I'm doing this at the airport, so edited directly on github; I hope I didn't mess up the links...)

Installation issue opened in #6154, merging...

Thanks, @kelle!