Originally thought the touch-icon stuff in the templates was a funny name for the logo, but it's something else. Logo stuff isn't actually included, it's in the sites containing the themes. For example, in Requests, the logo and other sidebar bits come in like so:

• Sidebar config
• Sidebar content

Hopefully doable to pull that stuff into the theme and make it configurable via html_theme_options.

It's even worse than the old Gittip one, it floats real high up on its line and looks grody. Unclear if there's a good way to fix that; may need to work around by changing its presentation (eg move to its own line?)

I've had a few pages get long, where having the navigation scroll with the content would make jumping around the docs much more comfortable.

What about something like the Bootstrap docs navigation sidebar? There's a good breakdown here that builds the behavior in layers.

Even without attaching a scrollspy to highlight the current location, simply fixing the navigation to scroll with the content would be a nice enhancement.

Hello,

I'd like to add a Twitter account link to the side bar, right below the Github button. How'd I do that? Which template do I need to edit?

I wrote this docstring:

def bar(age):
    """
    this is bar function

    >>> import foo
    >>> foo.bar(10)
    10

    This function just return age.

    :param int age: your age
    :return: age
    :rtype: int
    """
    return age

and built with using 'classic' theme, I got this image:

I git this image with using 'alabaster' theme:

It would be better to understand the document if gray box for doctest lines doesn't protrude outside the docstring content area.

h2 and h3 look super similar on my main browser (Chrome) and this makes many documents hard to read. Try making h3 (and thus h4 and so on) smaller.

It'd be great if there were links to the previous and next posts in every page (where applicable).

(By the way, thanks for the theme! I like it a lot)

techtonik/mingwpy.github.io@7ea6b18

Does it worth adding an option?

So we oughtta change:

• settings/variable names
• text/label before sidebar button
• Possibly CSS or something of sidebar button (now looks cut off) - see https://gratipay.com/bitprophet/widgets/ for modern example

to prevent the image from exceeding the page width?

or probably img max-width ?

I'm using alabaster for a project site, and it's not rendering html_theme_options (or about.html or any of the rest of the theme aside from the styles). Here's a gist of my configuration, it seems like I'm doing everything according to the README, but does that look right? What else can I provide?

Sphinx==1.2.3
alabaster==0.6.3

Edit: to be clear, it renders like this, despite having the logo and github options set (or so it seems?):

The theme looks amazing with Garamond, which unfortunately isn't installed on OS X by default. It'd be super sweet if there was a webfont for this.

Dear Jeff,
congrats for your alabaster ext. I love it!
I encounter problems in changing the ugly border of the bibliography entries (generated by sphinx-contrib-bibtex): they appear by default in tables with 1px border and I haven't succeeded in putting it without border (but I need that regular tables to keep their border as well).
This might be changed in the theme.conf file.
See end of this file: http://webcom.upmf-grenoble.fr/sciedu/pdessus/sapea/innovation.html
Thx for your help in advance!
best
philippe

I have some documentation up here: http://django-pagetree.readthedocs.org/

How do I make the top left of the page be a link to the root of the documentation, with the title of the package (django-pagetree) instead of the text "This Page"?

The docs for the logo options state:

If logo is not set, your project name setting (from the top level Sphinx config) will be used in a text header instead. This preserves a link back to your homepage from inner doc pages.

But that doesn't seem to be working for me.

(maybe this is a more general sphinx question, rather than alabaster specific?)

When you run sphinx-quickstart, it generates 3 links on the index page:

• :ref:genindex
• :ref:modindex
• :ref:search

Alabaster allows you to add a search box in the html sidebar (searchbox.html), but when I try adding genindex.html nothing gets shown. I've tried adding :ref\genindexto the`toctree`too, but that generates a warning of`WARNING: toctree contains reference to nonexisting document u':ref:/`genindex/

Intriguingly, when I do both of the above, I get an additional warning of Recursion error: maximum recursion depth exceeded in cmp.

One potential solution appears to be in this Stackoverflow answer, but this would only add it as an additional link; I have actually managed to achieve this in an alternative way by adding 'Index' : 'genindex.html' to the 'extra_nav_links' dictionary - but this doesn't seem particularly elegant because it doesn't use the :ref: cross-referencing syntax

Can you upload wheels of alabaster to pypi as per https://packaging.python.org/en/latest/distributing.html#wheels, as it makes alabaster faster to install.

I'd like to see Bitbucket analogs for the GitHub start buttons / banner options.

The following look pretty good: http://bb-btns.bitbucket.org/
FontAwesome has a Bitbucket icon that might be good to use too.

I've got laid out my documentation using the following structure:

.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    ├── content
    │   ├── section_01
    │   │   └── topic-01.rst
    │   │   └── topic-02.rst
    │   ├── section-01-root.rst
    │   ├── section_02
    │   │   └── topic-02.rst
    │   └── section-02-root.rst
    └── index.rst

When on a page, it's not obvious what section you're in. Do you have any suggestions of how I might implement a 'breadcrumbs' style page title with alabaster (making it obvious where you are and easy to navigate back towards the root of the documentation)?

Right now is says

github_button_type: Defaults to watch.
github_button_count: Defaults to true.

but should be

github_type: Defaults to watch.
github_count: Defaults to true.

Continuation of #35, the navigation in the sidebar does not link to any indices, such as one created by the autohttp. https://github.com/bitprophet/alabaster/compare/master...tpievila:related?expand=1 shows how it was done in the old default theme, and seems to work also with alabaster (though no comment on how good it looks...).

There are no localized titles it the sidebars, eg. "Navigation", "Next", etc. It looks bad, when whole sphinx-doc is localized, but final web page is not and one need to customize the templates...

While working on #44 I discovered that document text gets clipped under ~911 px but the nav doesn't move until 875px.

I uploaded three images to show off the problem with the current breakpoints and the default theme width.

Where are the 875/870px numbers from for the media queries?

After #21 I find myself wondering if seealso blocks shouldn't still have some other color to differentiate themselves from note blocks.

Quick check of other themes re: seealso vs note:

• snide/sphinx_rtd_theme does not differentiate between note / seealso at all.
• Sphinx default and traditional themes set note to gray and seealso to the same yellows our source theme(s) do (unsurprising since presumably Armin worked off of the default originally).
• The 'bootstrap' theme doesn't appear to style seealso at all, though it sets note, warn and danger to distinct colors aligning with (surprise) Bootstrap: http://ryan-roemer.github.io/sphinx-bootstrap-theme/examples.html#admonitions

Want this for a few reasons:

• Logo placeholder text looks pretty fugly as serif, even if body text looks OK as serif
• At least one user (who happens to, you know, be the primary Sphinx developer...:D) requested general font control & it's just a good idea.

Basic implementation: single option controlling the value of font-family (which is currently 5 fonts, presumably most of which are serif since that's what most people see). Default to currently hardcoded value.

Alternate implementation: single option that appends/prepends (I forget how the ordering works for font-family offhand) to existing hardcoded value. This gives us a known baseline while still allowing overrides. Only downside is if, somehow, having "our" fonts in the list anywhere causes issues despite user append.

Deeper implementation: separate font options for logo placeholder, body text, and maybe sidebar & footer. Not sure this is a great idea - how many well designed sites do this?

Copying or using submodules is shitty.

I like the approach Dave/Eric used for the new RTD theme - it just follows Sphinx's notes for how to distribute via PyPI, then the boilerplate for users simply calls a method in the distributed code that spits out "where am I?" (instead of assuming local _themes.)

Let's give that a try here. Salient bits:

• https://github.com/snide/sphinx_rtd_theme/blob/master/setup.py - make sure files get distributed correctly
• https://github.com/snide/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/__init__.py - aforementioned boilerplate method (and version stuff, which I might move elsewhere.)

Hi

In commit a8c8b2c should this be:

with open('README.rst'), encoding='utf-8') as f:
    readme = f.read() 

I'm getting the following error when building using python3 (on the opensuse build server)

 python3 setup.py build
[   97s] Traceback (most recent call last):
[   97s]   File "setup.py", line 13, in <module>
[   97s]     readme = f.read()
[   97s]   File "/usr/lib64/python3.4/encodings/ascii.py", line 26, in decode
[   97s]     return codecs.ascii_decode(input, self.errors)[0]
[   97s] UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 15684: ordinal not in range(128)
[   97s] error: Bad exit status from /var/tmp/rpm-tmp.SU1PL3 (%build)

see https://build.opensuse.org/package/live_build_log/home:apersaud:branches:devel:languages:python3/python3-alabaster/openSUSE_13.2/x86_64

No recollection of how this got muddled, but apparently some Sphinx installs (or plugins) generate "admonitions" which are NOT "warns". E.g. .. warn:: generates <div class="admonition warn">, and Alabaster themes 'warn' blocks by applying color to div.admonition. This "works" well enough and IIRC I was following earlier CSS rules when I made the change.

However, sphinx-doc/sphinx#1825 has a user who's somehow creating <div class="admonition-test admonition"> from a plugin, which he doesn't want to be red, and which are not intended to be 'warn' style blocks.

Glancing at our stylesheet, it does look like we could move the color styling to div.warn and it should continue to function while not polluting generic/overridden admonitions.

A few tiny problems with gittip:

• The link in the text blurb above the button is the same as the button - should the button be going somewhere different?
• If the answer is "no", probably remove the link in the text, or make it link to Gittip's index page (and link just Gittip not on Gittip).
• Formatting feels like it might be off too. This element doesn't even show up on requests' current site, so maybe it's outdated.

Allow users to disable the "Powered by Sphinx xxx & Alabaster yyy" bit in the footer with a boolean option.

At request of one K. Reitz.

• Git SHA of current build
• Add RTD+link to 'powered by' section if env var is set

As far as I can tell from Sphinx's own docs, users can inject static files by themselves by throwing _t files into their html_static_path (defaults to empty list but of course configurable in users' conf.py).

That gives them the ability to insert CSS files, and thus, lets them override built-in styles without us needing to expose literally everything as a config option (just...almost everything).

The missing piece, then, is that our templates need to slap another <link> tag into the extrahead block so that the resulting HTML tries loading such an auxiliary CSS file. I don't see the basic theme (which we inherit from) doing this as-is, so it does fall to us. Should be trivial.

This would incidentally solve #76.

Not sure if this issue should go to sphinx itself, but the new recommendation to use alabaster in 1.3 causes some unexpected behavior with domains providing indices: the navigation div is not visible with alabaster, unlike in classic.

For example the httpdomain creates a routing table page, and links to it in the navigation div:

<div class="related" role="navigation" aria-label="related navigation">
  <h3>Navigation</h3>
  <ul>
    <li class="right" style="margin-right: 10px">
      <a href="genindex.html" title="General Index"
         accesskey="I">index</a></li>
    <li class="right" >
      <a href="http-routingtable.html" title="HTTP Routing Table"
         >routing table</a> |</li>
  </ul>
</div>

• Move README to ReST, partly so PyPI displays it correctly (ugh)
• Set up basic Sphinx tree splitting up the README, which is now huge
• Transmute changelog to use Releases
• Figure out bizarro "part of the changelog entry for #51 is being cut off" issue. EDIT: actually it impacts a LOT of line items, odd.
• Update any appropriate setup.py metadata (long_desc should be ok if pulling in now-short README; doublecheck project website field, it will need to be RTD site instead of github; etc)
• Set up RTD site
• ??? - check - I'm always confused
• Profit - This is free software, whoops

The bullets and text are all flattened to the same horizontal alignment.

To reproduce

1. Put the following in a Sphinx document:
   • a
     • b
       • c
     • d
       • e
   • f
     • g
   • h
2. Render using the Alabaster theme
3. Make your browser less than 870 browser pixels wide.
4. The bullets will be different, but all bullets and text should be aligned.

Hello,
sorry for posting to "Issues" but I could not find another location.

Is it possible to enlarge the font size of the the embedded equations
in Alabaster (or Sphinx in general)?

I only found .MathJax {font-size: 1.3em;} somewhere, but I am not
that familiar with CSS.

Kind regards,
Joe

I find the typeface to be too thin for continuous pleasant reading and would consider something akin to Georgia (which Flask uses for example) to be better. It's also bigger, but the typeface definitely plays a larger role.

I suggest opening the images in new tabs for optimal viewing (github resized them).

source: http://docs.python-requests.org/en/master/

source: http://flask.pocoo.org/docs/0.10/errorhandling/

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?

Cuz putting your stinkin' badgers at the top of your README feels kinda grody, especially when you use your README as the front material on the website.

I'd rather lose the badges on the Github landing page and have them arranged more nicely on the real website, for projects that have real websites. Which, if they're using Alabaster, they by definition do.

Note: not make more colors configurable, but make some elements that are currently transparent or black and white, colored (though these would of course be configurable too).

Cribbed from #6 and #28:

It also made me realize that it'd be nice to just have a bit more color in the theme overall. Not so much as to undermine its low-key feel, but enough that one can make an Alabaster site look different from the default w/o resorting to custom stylesheets.

Add more colored elements overall, e.g. perhaps make some thick top or bottom borders on headers or on the sidebar or something. Some common visual elements that stand out a bit and can help tell Alabaster-using sites apart with a single color change.

2fd2500#commitcomment-11680683 - seems to still be present in master.

Haven't heard any other complaints about this causing render issues but it definitely looks spurious, my guess is it's due to an older template that was using a horizontal UL/OL for footer bits.

tl;dr let's make all the coloring configurable, right now only ~30-50% of the common elements have configurable color options.

• 'See also' blocks are yellow background & font sizes feel off. This element does not appear at all in Requests' docs so suspect this styling is inherited from the basic theme or something. Fix it up.
• Similarly, 'warning' blocks have zero color styling, they should be a controllable color that defaults to a pleasing shade of red.
  • This is especially important as RTD inserts a warning block (a div class='admonition warning') for 'on an old version' notices.
• Note blocks are currently one of the gray colors; see if they might want to be something else?
• dt:target, .highlight rule is light-colored but idk what it actually maps to offhand.
• hr is colored but is not used often in (my) Sphinx docs, so it's been left alone for now
• Body background is hardcoded to be white right now, might as well make it an option sometime
• div.admonition tt.xref, div.admonition a tt - not entirely sure what these are offhand
  • DItto top-level tt
• div.topic - also not sure where this appears, topics are usually header tags?
• img.screenshot, table.docutils (+ sub-items), ???

Request for a config variable for the background color.

Have logo img + text looking OK, but required some dumb CSS futzing. Need to test both other configurations, & other browsers (I use Chrome normally):

• no configured logo (just text)
• logo image and no text
• Firefox
• Safari
• IE I guess...depends what's on my PC

Should be the final step - set up some colorization options so sites can easily differentiate with more than just the logo.

Originally had a list here but now simply going through the CSS and replacing nearly everything with an option (except elements that really don't need it or which don't currently get displayed in HTML but aren't worth deleting.)

See also #6

See topic.

When adding:

.. tip:: Something

It gets formatted using a red notice frame, which is not appropriate for tips. I believe it should have the same formatting as regular notes

Hi, could you add another {% if %} in the layout footer to hide "©." if html_show_copyright is False?
http://sphinx-doc.org/config.html#confval-html_show_copyright

My navigation section is only displayed on my index.html page, navigating to any other page will leave the navigation sidebar blank. Anyone know what i'm doing wrong?

index.rst:

.. CALIPSO documentation master file, created by
   sphinx-quickstart on Tue Jun 09 15:49:16 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

============================================================
Welcome to the Visualization of Calipso Tool (VOCAL)!
============================================================

Everything you'll need to know from installation to developing the application can be found here!
 VOCAL aim's to have a very in depth doc page in order to promote open source development 
and allow for VOCAL to evolve as the users see fit. Refer to the side bar on the left to navigate 
about the doc page, and use the search button at the top corner if you're looking for specific areas.

.. toctree::

   overview
   installation
   gettingdata
   supporteddata
   tutorial
   dev/conventions
   dev/enviroment
   dev/docs
   dev/site
   doc/modules
   trouble/faq
   trouble/issuetracker
   trouble/contact

Generates

Looks all great, but clicking any link leaves me with

Where'd the navigation bar go? Do I need to specify something?

By default the github_button option is true, but no user / repo have been supplied. This means that your site shows a "stars" button that links to https://github.com//.

The button should not be shown if the user / repo have not been supplied (even if the github_button option is left at its default true setting).

Pros: badges are cool, supporting RTD is cool.

Cons: Given most Alabaster sites are likely to be hosted on RTD it feels a little silly having a link-to-self in the sidebar; and if the build is broken, how will you know? You're either seeing some working version of the docs, or you're seeing a 404 page (and not the badge) XD