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.
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.
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.
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
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.
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/rackerlabs/docs-core-infra-user-guide/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.
.. 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:
@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.
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.
When I remove the <self> notation to make a pure link, the javascript on the page is creating href = with nothing in it. Explain more about why you think <self> is the root cause here?
Find the lines corresponding to the title in the ToC. (Line 214 currently)
Observe that the href attribute for the title link is empty, meaning clicking this link will always navigate a user to the current page (essentially a no-op):
Because the empty href appears in the server-rendered output, before any client-side JavaScript has been parsed, we can conclude that client-side JavaScript is not responsible for this problem.
Proof: deconst presenter and/or plugins aren't the problem
Check out the master branch of rackerlabs/docs-core-infra-user-guide and pull the latest from GitHub.
Run the Sphinx preparer to build the Sphinx document into its deconst-ready payload:
docker run --rm -it -v $(pwd):/usr/content-repo quay.io/deconst/preparer-sphinx
This will create the directory _build/deconst-serial and fill it with several directories and JSON files.
Run less _build/deconst-serial/_toc.json to scan the ToC envelope in less.
Type /Cloud Core to highlight the title link. It should be near the beginning of the file.
Observe that the hyperlink wrapping the title has an empty href attribute, meaning clicking this link will always navigate a user to the current page.
Because the empty href appears in the output of the Sphinx preparer, before the presenter has even seen the envelope, we can conclude that the deconst presenter is not responsible for this problem.
Proof: preparer-sphinx isn't the problem
Check out the master branch of rackerlabs/docs-core-infra-user-guide and pull the latest from GitHub.
Run make json to use one of Sphinx's own builders, and not preparer-sphinx
Run less _build/json/_toc.fjson to scan the ToC envelope.
Type /Cloud Core to highlight the title link. It should be near the beginning of the file.
Observe that the hyperlink wrapping the title has an empty href attribute, meaning clicking this link will always navigate a user to the current page.
Because the empty href appears in the output of Sphinx's own builder, we can conclude that the preparer-sphinx is not responsible for this problem.
Conclusions
This is not a template issue.
This is not a presenter issue.
This is not a preparer issue.
The problem must lie within Sphinx itself.
I would recommend closing this issue and re-opening https://github.com/rackerlabs/docs-core-infra-user-guide/issues/408 as the root of the issue needs to be discussed and solved there. There may be minor adjustments necessary in this repo to accompany the eventual solution, but the root issue does not belong here.
@annegentle commented on Fri Apr 01 2016
@trentgillaspie commented on Wed Dec 23 2015
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.
@rose-coste commented on Wed Dec 23 2015
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.
@trentgillaspie commented on Mon Dec 28 2015
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.com<mailto:notifications@github.com> Reply-To: rackerlabs/docs-core-infra-user-guide reply@reply.github.com<mailto: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.com<mailto:docs-core-infra-user-guide@noreply.github.com> Cc: Trent Gillaspie trent.gillaspie@rackspace.com<mailto: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/rackerlabs/docs-core-infra-user-guide/issues/408#issuecomment-167010397.
@stephamon commented on Mon Mar 14 2016
@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.
@annegentle commented on Thu Mar 31 2016
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
@annegentle commented on Thu Mar 31 2016
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
@ktbartholomew commented on Thu Mar 31 2016
pruneRoothas 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.@annegentle commented on Fri Apr 01 2016
Moved to nexus-control since the template is there.
@annegentle commented on Fri Apr 01 2016
When I remove the
<self>notation to make a pure link, the javascript on the page is creatinghref =with nothing in it. Explain more about why you think<self>is the root cause here?@ktbartholomew commented on Fri Apr 01 2016
Let's work through the scenario backwards to rule out possible culprits:
Proof: client-side JavaScript isn't the problem
Observe that the
hrefattribute for the title link is empty, meaning clicking this link will always navigate a user to the current page (essentially a no-op):Because the empty href appears in the server-rendered output, before any client-side JavaScript has been parsed, we can conclude that client-side JavaScript is not responsible for this problem.
Proof: deconst presenter and/or plugins aren't the problem
masterbranch ofrackerlabs/docs-core-infra-user-guideand pull the latest from GitHub.Run the Sphinx preparer to build the Sphinx document into its deconst-ready payload:
This will create the directory
_build/deconst-serialand fill it with several directories and JSON files.less _build/deconst-serial/_toc.jsonto scan the ToC envelope inless./Cloud Coreto highlight the title link. It should be near the beginning of the file.hrefattribute, meaning clicking this link will always navigate a user to the current page.Because the empty href appears in the output of the Sphinx preparer, before the presenter has even seen the envelope, we can conclude that the deconst presenter is not responsible for this problem.
Proof: preparer-sphinx isn't the problem
masterbranch ofrackerlabs/docs-core-infra-user-guideand pull the latest from GitHub.make jsonto use one of Sphinx's own builders, and not preparer-sphinxless _build/json/_toc.fjsonto scan the ToC envelope./Cloud Coreto highlight the title link. It should be near the beginning of the file.hrefattribute, meaning clicking this link will always navigate a user to the current page.Because the empty href appears in the output of Sphinx's own builder, we can conclude that the preparer-sphinx is not responsible for this problem.
Conclusions
I would recommend closing this issue and re-opening https://github.com/rackerlabs/docs-core-infra-user-guide/issues/408 as the root of the issue needs to be discussed and solved there. There may be minor adjustments necessary in this repo to accompany the eventual solution, but the root issue does not belong here.