Use html_short_title instead of html_title in Navigation Bar

[nfarrar]

New to sphinx & alabaster - sorry if this is a silly question. I'm looking for a way to use a shorter title in the navigation bar - my long title doesn't fit nicely there.

From what I've experimented with so far, it seems that the navigation page title is hardcoded to use the value of project_title - and ignores both html_title and html_short_title. I was hoping there might be an alabaster option (or generic theme option alabaster respects) somewhere that would let me do something like:

# set the title used in the navigation bar to html_short_title instead of project_title
html_theme_title = html_short_title

Any suggestions?

[bitprophet]

More options sounds great; but can you link to a screenshot or other example making it super clear which element you're referring to? Thanks!

[nfarrar]

Yup - here's an example:

relevant statements from config.py:

project = u"My Project Name"
html_title = 'My HTML Title'
html_short_title = 'Project'
# html_logo = 'logo.png'

html_theme_options = {
    # Display the logo in the sidebar. If html_logo is set, the logo will
    # be displayed twice. This also suppresses the project name from being
    # displayed at the top of the sidebar.
    'logo': 'logo.png',

    # If logo is set, this will display the project name *under* the logo.
    # This is hardcoded to the *project* name.
    'logo_name': True,
}

Essentially - I was just hoping to have "Project" (html_short_title) at the top of the navigation bar, rather than the project name.

[bitprophet]

Gotcha, thank you! Yea I don't think we make this easy or even possible right now. I don't recall even being super aware of these core Sphinx html_* options before now, wonder how old/new they are.

At least, we could make the value for that element controllable; and ideally we'd be able to say "refer to html_title's value" (or similar) as you were describing.

If we wanted the field to be totally controllable (as in, an arbitrary value differing from the values of project, html_title and so on) and able to "refer" to the other values, that would be a tad messy because Sphinx configs basically get coerced to strings always - we'd need sentinel strings or something. However, in this case I suspect it'd be fine to just name the new setting something like title_source and make it clear it only accepts names referencing other fields/variables.

I don't have time to poke this myself right now but I'd consider merging a PR :) thanks!

[nfarrar]

Gotcha thanks. I haven't taken the time yet to figure out how to build my docs using the sphinx source (vs. the pip installation). Any chance there are some instructions somewhere that I missed that show how to setup a sphinx project with an alabaster source install for development (I'm new to sphinx in general, and haven't taken the time to figure out all the internals yet)?

[bitprophet]

When I use Alabaster I just have Sphinx installed as normal and then Alabaster installed via pip install -e /path/to/my/alabaster/checkout and that generally works - if I build Sphinx docs in that virtualenv, it uses that Alabaster checkout. The Sphinx itself can be totally vanilla from pip.

IIRC that will suffice because Sphinx just relies directly on e.g. import alabaster, i.e. it does not vendor it or anything. If that's not enough, you might need some of the other Sphinx settings like those here: https://github.com/pyinvoke/invoke/blob/ce3f6078277f243cfe8e6e27b8151dd3e3d2494f/sites/shared_conf.py#L3-L26 - I think that is cruft now that I could be removing on my end, but not positive.

[willvousden]

Can't we just make it take an arbitrary string?

If you want to use the value specified in another config variable, that's easy:

project = u"My Project Name"
html_title = 'My HTML Title'
html_short_title = 'Project'

html_theme_options = {
    'logo_name': html_title_short,
}

For backwards compatibility, True could be special-cased to indicate that the project string should be used.

I'll have a go at making a PR for you...