Link to the documentation index missing

[havatv]

There used to be an index available from the documentation page. Now I can't find it. Don't know when it disappeared.

An index is useful, and we have done a lot of work to add index entries, so it would be nice to get the index back.

[sdlime]

So this was a separate page linked to from the documentation page?

[havatv]

I just checked a 6.4 build, and the file with the index is build/html/genindex.html.
The file name is the same for 7.0 (http://mapserver.org/genindex.html), but there the link is not shown anymore.

The link used to be in white text on the right side in a thick horizontal blue line below the flags.

[havatv]

All translations have the blue line with the index link. It is only on the main language (English) page that the blue line with the index link is missing.

The following is the blue line for the German translation:

<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="Stichwortverzeichnis"
         accesskey="I">Index</a></li>
    <li class="right" >
      <a href="about.html" title="Hintergrund"
         accesskey="N">weiter</a> |</li>
    <li class="nav-item nav-item-0"><a href="#">Home</a> &raquo;</li> 
  </ul>
</div>

When compiling the docs locally, the blue line shows up also for the main language "front" page:

<div class="related">
  <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="about.html" title="About"
         accesskey="N">next</a> |</li>
    <li><a href="#">Home</a> &raquo;</li> 
  </ul>
</div>

[havatv]

@jmckenna, could you have a look at this? I think the current situation is very unfortunate, as it makes navigating the documentation very difficult for those that use the default (English) version of the documentation.

[havatv]

Update:
Now the blue navigation line has also disappeared from the (non-US) translations.
To recap: When compiling locally, the blue line shows up as expected. The code that brings up the line is:

<div class="related">
  <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="grid.html" title="GRID"
         accesskey="N">next</a> |</li>
    <li class="right" >
      <a href="fontset.html" title="FONTSET"
         accesskey="P">previous</a> |</li>
    <li><a href="../index.html">Home</a> &raquo;</li>
      <li><a href="../documentation.html" >MapServer 7.0.0 Documentation</a> &raquo;</li>
      <li><a href="index.html" accesskey="U">Mapfile</a> &raquo;</li> 
  </ul>
 </div>

That code comes directly after the table that contains the translation links (with flags). On mapserver.org, the code is not there.

A lot of effort has been put into the MapServer documentation index, and it is a real shame that it is not available. With the large amount of documentation, having access to the index is essential!

[jmckenna]

Hi @havatv I will take a look

[jmckenna]

The current status is that I have fixed the default English page to include the navigation bar (apparently my fix helped another Sphinx community who was stuck on this for months, ha). But I haven't figured out yet why it won't appear on any of the translated pages.

I did figure out why locally for my own builds I would have duplicate navigation bars. It turns out that Sphinx uses several default "layout.html" files, and I had to check a few of them locally on my own machine:

• C/Python26/Lib/site-packages/sphinx-1.3.1-py2.6.egg/sphinx/themes/basic/layout.html
• C/Python26/Lib/site-packages/alabaster-0.7.4-py2.6.egg/alabaster/layout.html
• and of course ours at /_templates/layout.html

If you are a doc maintainer and you have duplicate navigation bars for local builds, I'd ask you just live with them for now, and be happy for now that travis-ci.org and mapserver.org has at least 1 navigation bar (for English).

I will keep digging on this. Not easy, as unfortunately this is all done through travis-ci.org "cloud" builds. PS I hate the cloud.

[havatv]

Thanks for the quick fix, @jmckenna!

[geographika]

I've been looking into this issue recently. The "alabaster" theme became the default for Sphinx within the last year, and hides the relbar by default.

See Lib\site-packages\alabaster\layout.html

{# Disable base theme's top+bottom related navs; we have our own in sidebar #}
{%- block relbar1 %}{% endblock %}
{%- block relbar2 %}{% endblock %}

By explicitly setting the theme to classic (which is what was used by Sphinx previously) the bar comes back. There is also one at the bottom - this can be overriden in the MapServer layout.html if needed.

[jmckenna]

indeed, that i why i mentioned alabaster earlier here (C/Python26/Lib/site-packages/alabaster-0.7.4-py2.6.egg/alabaster/layout.html).

[geographika]

@jmckenna - looking at the alabaster theme it seems it is nearly all overridden anyway, so by bypassing that in the conf.py file the docs should build with the navigation bar on the travis-ci build?

[jmckenna]

the issue before was making this all work both locally and on Travis, indeed I did spend much time on that.

[jmckenna]

Let us see how it goes on Travis......

[jmckenna]

@geographika please check how your changes look on mapserver.org (Travis) now. Likely it is the same result and explanation as I said in my earlier Oct 21 comment.

[geographika]

@jmckenna http://mapserver.org/ looks good for me now - at least it has the blue bar back underneath the title so you can navigate more easily between sections (and access the index).
The translated versions still have it missing, but it appears they were not updated by the Travis build. They still refer to the Alabaster theme at the bottom of the page.

[jmckenna]

@geographika the blue bar was back, on mapserver.org, placed back through my Oct 21 changes. The only issue remaining was the blue bar on the translated pages. (in your case, you likely had both issues, as I mentioned back on Oct 21).

[jmckenna]

in any case, the issue then and the issue now is the darn blue bar, only on translated pages, and only on Travis/mapserver.org So, the issue remains open :)

[jmckenna]

Anyway I am fine if you want to close this, but in my mind the issue exists the same now as it did on Oct 21. Maybe I am wrong, I am often wrong :)

[jmckenna]

Maybe all that is needed is a [build_translations] commit?

[jmckenna]

darn Travis :)

[jmckenna]

I'll try to build all translations on Travis now...

[jmckenna]

translations are building now on travis: https://travis-ci.org/mapserver/docs/builds/167503564

[jmckenna]

@geographika can you check mapserver.org now?

[jmckenna]

(i had to clear my browser cache) ok too many messages from me I guess! Cheers from Canada.

[geographika]

Looks good now!
The blue bar had been missing again on mapserver.org for the last few weeks - I think due to the requirements.txt update on August 23rd 2016. I had the blue bar locally until I changed to alabaster version 0.7.9 which removed the relbar - sphinx-doc/alabaster@f82f9db

[jmckenna]

True, I bet as I had been updating requirements.txt that a recent change killed it again for good ha (I also have Alabaster 0.7.9 locally). Thanks @geographika and great teamwork! Yikes this one was tricky. I think we can mark this as closed. (!!) Cross your fingers.