rackerlabs/docs-core-infra-user-guide

Top left link on Core Infra. Guide should take me to top-level guide page

trentgillaspie opened this issue · 10 comments

https://developer.rackspace.com/docs/user-guides/infrastructure/
When I navigate to the URL above, and browse away from the landing page. When I try to get back to the URL above by clicking on "Cloud Core Infrastructure User Guide," the link does not take me anywhere. The link should take me back to the URL above.

Screenshot attached, with link called out in blue text.

screen shot 2015-12-23 at 2 54 45 pm

Hi, Trent,

I know about this problem; I don't know how to fix it. @meker12 & I have talked about it; we'll get back to it soon. Thanks for opening the issue to make sure someone eventually gets to the bottom of it.

You can see the same bad behavior in the Orchestration Templates User Guide (https://developer.rackspace.com/docs/user-guides/orchestration/) and in API Developer Guides
(such as https://developer.rackspace.com/docs/cloud-identity/v2/developer-guide/).

We all have the same problem because we all copied this feature, adding a guide's title to the top of its left-hand navigation tree, from each other. Figuring out a better way will fix us all, too.

Thanks, Rose.

Yes, it looks like the same issue is occurring in those other two areas as well. It would seem a simple linkage may solve the problem, but my unfamiliarity with the exact code may mean there is a little bit more finagling behind the scenes. I'll stay tuned here for updates. Thank you.

Trent Gillaspie

Rackspace | Product Manager | 303.386.6115

Strategic | Futuristic | Communication | Responsibility | Arranger

/////////////////////////////////////////////////////

From: Rose Coste <notifications@github.commailto:notifications@github.com>
Reply-To: rackerlabs/docs-core-infra-user-guide <reply@reply.github.commailto:reply@reply.github.com>
Date: Wednesday, December 23, 2015 at 5:50 PM
To: rackerlabs/docs-core-infra-user-guide <docs-core-infra-user-guide@noreply.github.commailto:docs-core-infra-user-guide@noreply.github.com>
Cc: Trent Gillaspie <trent.gillaspie@rackspace.commailto:trent.gillaspie@rackspace.com>
Subject: Re: [docs-core-infra-user-guide] Top left link on Core Infra. Guide should take me to top-level guide page (#408)

Hi, Trent,

I know about this problem; I don't know how to fix it. @meker12https://github.com/meker12 & I have talked about it; we'll get back to it soon. Thanks for opening the issue to make sure someone eventually gets to the bottom of it.

You can see the same bad behavior in the Orchestration Templates User Guide (https://developer.rackspace.com/docs/user-guides/orchestration/) and in API Developer Guides
(such as https://developer.rackspace.com/docs/cloud-identity/v2/developer-guide/).

We all have the same problem because we all copied this feature, adding a guide's title to the top of its left-hand navigation tree, from each other. Figuring out a better way will fix us all, too.

Reply to this email directly or view it on GitHubhttps://github.com//issues/408#issuecomment-167010397.

@ktbartholomew any ideas on how to fix this issue? Seems like clicking on the doc title in the nav should take you back to the base index page, but it currently doesn't do anything at all.

I think the fix is something like what's in the Cloud Identity docs, where even in the hidden toc you have a specific link to the whole URL:

https://raw.githubusercontent.com/rackerlabs/docs-cloud-identity/master/api-docs/index.rst

.. toctree:: :hidden:
   :maxdepth: 2

   Cloud Identity API 2.0 <https://developer.rackspace.com/docs/cloud-identity/v2/developer-guide/#rackspace-cloud-identity-api-2-0>
   API Status <https://status.rackspace.com/>
   overview/index

Ok, more research. What's going on here is a pruneRoot directive in the docs-page.html template. When that is present, it prunes the root toc item using this javascript:

https://github.com/rackerlabs/nexus-control/blob/master/plugins/developer.rackspace.com/deconst-nav/filters/prune-root.js

@ktbartholomew why prune the root when users navigate in that <ul>? I want to get those pages to give the link to the landing page but don't want to ruin the original reason that mechanism was there.

cc @meker12

pruneRoot has nothing to do with the link not being generated correctly. It simply modifies the lists generated by Sphinx to get rid of some weird extra nesting that hampers with the UI.

The problem with that title link not working is that the the ToC generates relative URLs, which don't play nicely with a multi-page document. I don't recall how all the other links are getting turned into root-relative URLs, but the <self> notation on the title link is generating an empty hyperlink, which by definition links to the current page.

Heh dunno about that zenhubio thing.

As laid out in rackerlabs/nexus-control#392, The empty hyperlink for the title of the document is a problem with Sphinx's own behavior, and is not being directly caused by any deconst systems.

The way we generate the global ToC for documents like this is kind of peculiar, because as far as Sphinx understands it, the ToC would only be accessed from the root of the entire document. What we really need is a ToC for each page in a document that adjusts according that page's location in the entire document. (for example, the relative link in a deeply nested page might look something like href="../../../") Right now, the per-page toc property generated by Sphinx only shows the table of contents for the current page (e.g: one link for each heading on the page).

Generally, the way we're generating the global ToC right now is brittle and needs to be revamped. I've opened deconst/preparer-sphinx#51 to track the engineering efforts, but I think the discussion about the design of a better global ToC solution needs to happen here.

Okay, thanks for all this info that teaches us to fish 🎣 @ktbartholomew. Nicely laid out.

Testing the deconst-sphinx output with built-in sphinx commands (such as the make script locally) with my PR that has specific external links, I get this in the _build/json/_toc.json file:

{"meta": {}, "layout_key": "default", "body": "<div class=\"toctree-wrapper compound\">\n<ul>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"../cloud-guide-intro/\">How to use this guide</a><ul>\n<li class=\"toctree-l2\"><a class=\"reference internal\" href=\"../cloud-guide-intro/assumptions/\">Assumptions</a></li>

Here is the output for _build/deconst-serial/_toc.fjson when I use docker to use the preparer-sphinx from master:

{"body": "<div class=\"toctree-wrapper compound\">\n<ul>\n<li class=\"toctree-l1\"><a class=\"reference external\" href=\"https://developer.rackspace.com/docs/user-guides/infrastructure/\">Cloud Core Infrastructure User Guide</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"../cloud-guide-intro/\">How to use this guide</a><ul>\n<li class=\"toctree-l2\"><a class=\"reference internal\" href=\"../cloud-guide-intro/assumptions/\">Assumptions</a></li>

The part I want to understand is <li class=\"toctree-l1\"><a class=\"reference external\" href=\"https://developer.rackspace.com/docs/user-guides/infrastructure/\">Cloud Core Infrastructure User Guide</a></li> -- why does that get changed to href= when the page content is served through deconst?

I'm thinking of some sort of band-aid 🏥 fix while the better toc is designed, where the preparer-sphinx inserts href="index.html" for any root (instead of href=) and then we have redirects for every route we indicate as a "guide's landing page." Thoughts?