Allow sidebars on index.html

[mlubin]

We're using JuliaDoc on RTD for JuMP's documentation (https://jump.readthedocs.org/en/latest/jump.html). RTD assumes that an index.html is present, otherwise many built-in links are broken; however, when we rename jump.rst to index.rst, the table of contents sidebar is no longer present.

I'm guessing this is related to:

def default_sidebars():
    """
    Returns a dictionary mapping for the templates used to render the
    sidebar on the index page and sub-pages.
    """
    return {
        '**': ['localtoc.html', 'relations.html', 'searchbox.html'],
        'index': ['searchbox.html'],
        'search': [],
    }

in __init__.py.

I could probably hack this locally, but could we make this more customizable so that it's easier for julia packages to use?

[pao]

I'm not sure what you mean; you can manipulate the return value of default_sidebars() (indeed, whatever you put in html_sidebars) all you want in doc.conf.py.

We could certainly consider changing the default, though, if that makes sense.

[carlobaldassi]

Just FYI: you guessed right, it's possible to change this locally by changing these lines on conf.py:

html_sidebars = juliadoc.default_sidebars()
html_sidebars['index'].insert(0, 'sidebarintro.html')

(note: not sure about what the second one does exactly) to something like:

html_sidebars = {
    '**': ['localtoc.html', 'relations.html', 'searchbox.html'],
    'index': [],
    'search': [],
}

and then modifying this according to your needs (e.g. removing the index entry would make the index page non-special).

[mlubin]

Right, I know it can be modified locally, but I'm looking to minimize the amount of custom configuration needed for a simple package. Not everyone writing documentation is a sphinx expert (that includes me). At the minimum, this should be mentioned in the readme.

[carlobaldassi]

I suppose it might be as simple as adding an optional argument to default_sidebars, e.g. skipindex defaulting to True, or something like that.

[pao]

I'd rather swap the default and make Julia's docs be the special case rather than introduce a special-purpose configuration option if that makes the most sense, but I think I'd like to wait until after 0.2 to do that.

[carlobaldassi]

Would it be possible to detect whether the docs are a single page, and in that case having default_sidebars put the sidebar into "index"? That seems like a reasonable heuristic to me.

[pao]

Not sure; would need to review the Sphinxification process. Good idea, though.

[mlubin]

Bumping this now that 0.2 is out.

[mlubin]

Bump again.