bootstrap theme for docs - initial layout - #209

Hmm... It is nice that this is more consistent with the web page. I also like the "astropy:docs" logo bit at the top. However, I have some concerns (that may or may not be fixable) with this layout.

1. I really don't like how narrow this is. It looks fine for a web site, but when I want to read documentation I don't want most of my (widescreen) real-estate wasted. This also causes weirdness in a variety of places - for example, the summary tables in the configuration system documentation (which you can take as a template of what most of them will eventually look like) breaks in odd places because of the narrowness, and doesn't look as much like a table. Also, some of the documented functions have weird justification because the narrowness forces line-breaks that leave a lot of white space.
2. I'm a bit put-off by the "contents" and "page" drop-downs. When browsing documentation, I usually find myself jumping around looking for specific things, and this effectively doubles the number of clicks I need to do that, as compared to the sidebar style. Is there a reasonable way to get the sidebar while still preserving the bootstrap look-and-feel? (I'm not sure if that would be good, but it would be nice to at least see to try to compare to this).
3. The landing page has only the TOC, and no general info. People will sometimes be landing at the docs without ever looking at the web page, so there should be some of the basic info here (although that can be updated later, I suppose).

Thanks for trying this out! I do think that pages that have more of a narrative look great, e.g.

http://kbarbary.github.com/astropy-docs/configs.html
http://kbarbary.github.com/astropy-docs/nddata/convolution.html

and I like the use of the bar just below the navbar. On the other hand, I find API and more technical pages (e.g. tables) hard to read, and I think these would require more work. Take for example:

http://kbarbary.github.com/astropy-docs/_generated/astropy.config.data.clear_data_cache.html

What is the function/method being described? You really have to look hard to figure out it's clear_data_cache, and I think the readthedocs css makes it clearer at the moment (of course this could be tweaked, so not a show stopper).

In any case, I feel like we should probably start by working more on the content of the docs to make them more wordy and less about just APIs - then we could try this theme again (with your tweaks), and if we like it, then work on the CSS to improve the API pages and tables in general. We have another ticket already open (#162) regarding the content of the docs though.

I agree with @eteq's critiques, but I like where this is going in general, and I think can be made to work.

While we're talking docs, I've always thought Flask's docs were very beautiful (both stylistically and content-wise): http://flask.pocoo.org/docs/ Just one example I think worth looking at for inspiration. I'm sure we could come up with many others.

@eteq / @iguananaut - Points taken. Details:

1. narrowness - Agree it can be wider. I just initialized it to the astropy-website width to see if it was workable, but we can do much wider or even 100%. In general, it's a battle between the narrative sections that want a smaller width for paragraph readability, and the technical sections with things like tables. I generally prefer some limit on width so you aren't trying to read lines that are 200 characters wide... But yes, it should be at least as wide as it needs to be for the technical sections to look good. [Specific to your example of the config API table, do you just mean the function descriptions wrapping to a second line, or are the functions themselves wrapping for you?]
2. Contents/page dropdowns - Heh, I sort of prefered having a sidebar as well, but I figured you guys liked the drop-downs since you picked this sphinx theme! I think it will "work" to put one or both of the drop-downs back into a sidebar, and I'd be happy to do it. Personally, I like the http://python.readthedocs.org/en/latest/index.html sidebar (with the hide/show feature) and would probably start by trying something like that.
3. I took the text off the landing page for now because some of it seemed out-of-date with the content on astropy.github.org. I'm definitely OK with putting some content back in there, but I think we should try to not "date" it with text like "While no releases have yet occured, development is occuring at the project’s github page." Should be limited to a sentence introduction (with link to website) and then information specific to the docs. For example, what http://flask.pocoo.org/docs/ has for an intro. As we progress in versions these docs will be built and then left to sit, right? (At least this is what numpy/scipy does.) So it seems better to not put in stuff that might be changed in the future (like links to mailing lists). For that kind of info, I think it is enough to clearly give a link to the astropy homepage. Otherwise you start to duplicate all the info on the homepage, and then what is the point of even having it?

@astrofrog - Yes, now that I look at it more closely, the bootstrap css leaves out a lot of sphinx-specific stuff that we'll have to put back in (such as monospace fonts!). However, I don't think this will be too hard. For example, look at the updated

http://kbarbary.github.com/astropy-docs/_generated/astropy.config.data.clear_data_cache.html

I think its close to what you get with readthedocs, and it wasn't too much work. There's plenty of other things that need tweaking (e.g. paragraph markers like you mentioned before). If people like the direction this is going, I'd be happy to do those tweaks.

I agree that the content needs reorganizing/expansion, but I'm not sure what the advantage is of waiting on the content - there's already enough there to see what narrative-y sections and table-y or API sections look like, and it would be nice to have this settled before v0.1.

Related to content reorgnaization, I think someone mentioned splitting the docs into a user guide and reference/API section. Do we want to do that? Personally I find having all the reference/API in one place (like for NumPy) very straightforward.

1. Ah, I see - If you add back in a sidebar, it will also help with the width being such a small part of the page. I marginally favor 100% because it doesn't bother me that much even in narrative docs, and it makes it more adaptable to a variety of different screen sizes... but that's fairly subjective. As long as it's wide enough that tables and lists look fine, a fixed limit should be fine. (And I was referencing the table that lists the config functions - the functions themselves don't seem to be breaking... although that's part of why there's less space for the description.)
2. I hadn't seen that hide/show sidebar for the python RTD docs before - I agree that's cool and would be great for this (although it would be nice to have the logo, as in the current RTD docs).
3. I agree the landing page shouldn't be "dated" - that's definitely something that needs to be fixed in the main docs. I just meant that the general overview information that's in the docs themselves should be on that page, rather than just a TOC.

@astrofrog / @kbarbary - I think the point here is that we want to have some general idea of how the large-scale content is to be organized before committing to this design (e.g. #162), but it's still good to start thinking about (and tweaking) this now so we're ready once we have more clean examples of how the docs are "supposed" to loc.

Regarding content/APIs: My thought was for something like the current astropy.config doc page to be roughly the idea here, where there's an initial narrative section, examples, and an API for each subpackage at the end. @iguananaut, this is actually the one thing I don't like about the flask docs - the API is segregated from the main docs, and as far as I can tell it really didn't need to be that way (although our organization makes that easier than flask, as we have clearer subpackage divisions). More on this in #162

I guess that's just a matter of personal taste then. I much prefer having the auto-generated API docs separate, and at the end. Usually if I'm reading the docs for a package I want to read the narrative overview of what the entire package has to offer me, without getting bogged down in any of the API details until I actually start doing something with it myself.

Obviously linking to the API docs is fine.

A new build is here: http://kbarbary.github.com/astropy-docs/
This is not yet ready for merging: we should wait for the resolution of #218 and for the docs to be updated to that layout and see how things look.
I just wanted to give people an update on what this is looking like after some of the issues have been addressed, and ask for any additional comments!

@kbarbary - it looks a lot nicer now!

One problem I'm still seeing, though: take a look at http://kbarbary.github.com/astropy-docs/configs.html - at least for me, the text runs off the sidebar into the main content. Do you see the same thing? I've noticed the same thing on the default theme (although for only one entry because of the way that sidebar is laid out), and RTD somehow fixed that. Perhaps look there for pointers on how to fix this?

I'm seeing the same problem with some of the other API docs as well.

@eteq Yeah the overflow is a problem. I actually opened an issue #243 that has a proposed solution.

By the way, I see the problem on the RTD docs as well. E.g., for http://docs.astropy.org/en/latest/configs.html the "Next Item" is astropy.config.data.clear_data_cache and that overflows. The only difference is that RTD theme sets the overflow to hide whereas my css doesn't. I could easily change it to hide, but I think the real answer is to make the title have shorter words, as I suggested in #243.

I see your point here - but can you set the overflow to hide anyway for this theme? Then, regardless of whether or not #243 is adopted, we still don't have the overflow problem. I think it's at least possible that in some few cases the overflow happens even if we don't have the fully-qualified names...

I like this a lot better now with the sidebar overflow thing fixed.

One final thing I noticed that seems weird: code examples (or anything else in a code block, for that matter) seem to have the same background color as the main page. Is that intentional? It makes it a lot harder to differentiate the code parts from the text parts...

@kbarbary - One other thing I noticed that's a bit probelmatic: see http://eteq.github.com/astropy/ , that's based off the latest master with your changes merged in. In particular, compare the sidebar for http://eteq.github.com/astropy/configs.html and http://eteq.github.com/astropy/table/index.html ... note that the former has all the API entries, but doesn't have any of the section titles from the current page. Can that be changed? Ideally, that would have entries for the sections on the page, and then a sub-section with API like in http://eteq.github.com/astropy/vo/index.html . Is there any way to do that without changing the doc format (that is, adding more pages)?

@eteq
codeblocks - yeah I didn't try too hard to customize these. Actually the page background is white and the codeblocks are "#eee", but you cant tell the difference on a crappy monitor (like mine) if you're slightly off axis. I'll play with making them darker. Any other styles (e.g., warnings, notes) people like from RTD that I should pull over?

Sidebar TOC - Well, none of your examples have section titles from the current page (including table and vo). There's an option in the toctree() function to include or exclude them. Currently I excluded them for two reasons. (1) I personally dislike internal links (ones that direct you to the page you're already on), particularly when it's not clear if they're internal or not - I want to know if the thing I'm clicking on is a different page or simply part of the page I'm already on. (2) A skeleton-in-the-closet with this theme is that the sticky topbars make it so that the internal links don't take you to the right place. (Try http://eteq.github.com/astropy/configs.html#for-developers .) Or they do, but the title is under the topbar.

A solution might be to list the local page titles, but not have them be links. This would put them in the TOC but make clear that they are on the current page.

By the way, I thought http://eteq.github.com/astropy/configs.html was the subpackage that follows the new standard rather than http://eteq.github.com/astropy/vo/index.html ?

@kbarbary: What would be involved in making the anchor links work (i.e. not hide the title under the topbar)? Sending anchor links to a particular part of a page is something I find really useful.

@mdboom You're right, this should be fixed. It's not something I personally use, but I definitely see the utility of the anchor links (sidebar issues aside). Unfortunately I'm no css/javascript expert, but I'll look into a fix.

@eteq regarding the sidebar:

I built two versions of the docs, one with titles_only = true in the sidebar TOC (what I had before) and titles_only = false (includes titles on the page).

• http://kbarbary.github.com/astropy-docs/table/index.html (titles_only = true)
• http://kbarbary.github.com/astropy-docs-v2/table/index.html (titles_only = false)

Personally I find the second version incredibly confusing. Its not at all clear which links are items on the current page and which will take me to a new page. If we really want to display the local TOC, I suggest we have a completely separate section in the sidebar, either above or below the "Table of Contents", and call it "On This Page".

@mdboom - apparently this is a common issue with fixed elements, and one that has a lot of halfway solutions but nothing perfect.

• http://stackoverflow.com/questions/4086107/html-positionfixed-page-header-and-in-page-anchors
• http://stackoverflow.com/questions/5070751/anchor-links-and-margins
• http://nicolasgallagher.com/jump-links-and-viewport-positioning/

I put one of these fixes in that works for our content and should work on any browser with pseudo-element support. Results viewable at http://kbarbary.github.com/astropy-docs/

@kbarbary

re: anchorlink: I like how it looks with the change you just made!

re: codeblocks/style: What you have now for code blocks looks good to me. Two (related) other things RTD does that I like (and hopefully aren't too hard to implement?):

• The Note and Warning (and presumably any other similar floating sections) have the "Note" and "Warning" titles offset from the content itself in a title bar. This makes them stand out more, which is important especially for warnings. As an example, compare the note and warning in http://readthedocs.org/docs/astropy/en/latest/configs.html and http://kbarbary.github.com/astropy-docs/configs.html
• The background color for notes in bootstrap is the same as the code block background color, so they stand out even less - RTD makes them a greenish color instead, which I like.

re: sidebar First, to clarify, yes, the config one is the one that follows the standard, rather than vo. I was pointing out that I liked how the sidebar looked in vo better than how it was laid out in config.

I agree that in your side-to-side comparison for table, v2 is more confusing... but now compare http://kbarbary.github.com/astropy-docs/configs.html and http://kbarbary.github.com/astropy-docs-v2/configs.html - I think in that case, v2 looks much better. As you pointed out, this is because most of the content is all on the one page rather than being separate pages.

I'm not exactly sure which version of the docs you're linking against now, though. It might be best if you rebase this against master so we can get a more up-to-date version of the docs? Or alternatively, merge it locally in your staging branch (perhaps even with #218), and use that to generate a new set of pages for kbarbary.github.com ?

I don't like the idea of non-linking entries, though - some of these pages will get pretty long (intentionally), and the point of having section links is that you can easily jump to them.

One final thing about the sidebar: can you make it float as you scroll the page? I'm not sure if others like that, but I find it quite useful...

@eteq I rebased on the current master.

styles: I made note and warnings look like RTD. I like them much better now.

scrolling sidebar: I had previously thought about this, but I think it is a bad idea - if the sidebar content is longer than your viewing window, you won't be able to access the bottom of it. The topbar only works well being fixed because its so short.

sidebar TOC: I built two versions of the docs again:

• http://kbarbary.github.com/astropy-docs/configs.html Global TOC only shows real pages. The local TOC (for the page) is in the sidebar under the global TOC.
• http://kbarbary.github.com/astropy-docs-v2/configs.html Global TOC displays everything.

I don't really like either of these. The structure in v2 makes a lot more sense, but the fact that you can't tell which things are on the current page and which are other pages is still a major sticking point for me. I'll think about it some more... thoughts?

One thing that might help is to put the "Reference/API" table on a separate page, at least for subpackages that have multiple pages of docs, and possibly even for ones with a single page like config. It will make the document hierarchy make more sense I think.

Also, you'll notice that everything under "developer documentation" got put in the global TOC at the top level, which I don't think we really want.

@kbarbary - the way readthedocs deals with the TOC is to have only the current top-level section shown - is that something we can do?

@astrofrog Yes, RTD just uses toc in the sidebar (produces the local page TOC) rather than the toctree() function (global TOC). We could do this. It would look exactly like http://kbarbary.github.com/astropy-docs/configs.html but just with the "On This Page" section of the sidebar, not the "Table of Contents" above it.

I would find this acceptable, as long as we called it "On this Page", not "Table of Contents". Seeing "Table of Contents" but having it be just the contents of the current page is something that I have found maddeningly confusing in the Sphinx built-in themes. If a person hasn't already seen a lot of Sphinx docs, "Table of Contents" makes one expect to see something like a book's TOC, which is the global TOC.

However, it would be a shame to lose the global TOC menu. It makes the layout of the docs and your current relative position in them clear at an easy glance, and makes navigating between different subpackages easy. Having the global TOC also makes the navigation similar to what I consider a standard navigation for a website with a lot of nested pages (for an example that matches nearly exactly, http://www.nersc.gov/users/computational-systems/hopper ). Without the global TOC in the sidebar, I find myself constantly clicking back to the main index page and using the TOC on that page instead.

@kbarbary - re sidebar TOC (everything else looks great, now): I really like v2 on the configuration page, although I agree it's a big problem that the front page mixes the developer docs with everything else... I'm not really bothered by the fact that you can't tell what's on which page for the rest, though. Is it possible to use a slightly different color for those that are on different pages? Then you could tell just by looking at the index.

I dislike v1, though - it's next-to-useless with the documentation format we're using, because most of the main content is on one page.

@astrofrog - I actually don't like the way RTD does it - I prefer v2 here because then you aren't stuck with only the current item when you switch to, say, a particular class or function - v2 still shows you the rest of the section.

@kbarbary - I agree that the global TOC is a very useful thing to have. Do you have a sense of whether it's possible to have both a "On this page" section and a "Table of Contents"? I think that would resolve most of these issues (I personally don't mind having them mixed, but I can see how that might be confusing to others).

Oh, and do we want to try to get this in for v0.1 ? I think it's almost there, so if we can get this sidebar TOC stuff straightened out, I'm happy with that.

@eteq Both an "On this Page" and a "Table of Contents": do you mean like v1 currently does? http://kbarbary.github.com/astropy-docs/ (The "On this Page" is below the "Table of Contents" right now - I think it might be better above it).

I don't think it is possible to color the links on the current page differently without modifying the sphinx function toctree(). You will notice that I colored the current page a dark color which I think is quite helpful in seeing where you are in the docs.

I guess my real problem is that I don't like the fact that Sphinx lets you define a TOC tree that doesn't necessarily match the hierarchy of the html pages. Short of insisting that all our docs are organized in a specific way so that the file layout and TOC tree match, my problem isn't going to be solved any time soon, so I guess we can ignore it. :) Having both "On this page" and the global TOC of documents seems like an OK compromise.

Oh, and I think it would be nice to have this for v0.1 if people think it's ready. Even more important though, I really hope the contents will be updated and homogenized before v0.1. (And are there docs for astropy.cosmology?) I suppose this mostly falls to the subpackage maintainers but if there's a part of this I can help with, let me know.

By the way, what do people think about the fixed top bar? I used to think it was nice but now I'm not sure. It seems like something that is more appropriate for a webpage rather than docs...

@kbarbary - whoops - I totally missed the "On this page" part of v1... sorry about that. It might make v1 better to switch the "on this page" and "table of contents", but I probably prefer v2 either way, because I don't really care that much whether it's on this page and would rather the sidebar by heirarchically themed by topic rather than location. As long as clicking on the link sends me to the right place, I don't really care what the URL is. @iguananaut, @mdboom, or @astrofrog, do you have thoughts on this?

As for the top bar, I think it's fine either way. You might add a link to the index and a link/icon leading to astropy.org, though (if it's easy).

And definitely we want to get everything on the same scheme by release (and I think we're on track to do so).

I'm closing this PR and opening a new one. I wasn't sure if I merged files correctly when I rebased, so I just started a new branch; it should definitely be a fast-forward.

@kbarbary - FYI in case it comes up in the future, it should work to rebase against astropy/master and then do "git push -f"... the PR will automatically update with the newly rebased version. (But opening a new PR is also fine!)