Add link to root of project documentation

[greschd]

From inside a project's documentation (e.g., https://dev.docs.pyansys.com/overview/index.html), there is no obvious way to get back to the project root (https://dev.docs.pyansys.com).

The logo in the top-left corner (which often takes this role) instead links to the root PyAnsys page https://docs.pyansys.com/.

I would argue that for a user looking at a specific page, it's more important to get to the root of that project, instead of the PyAnsys page. At the very least, there should be an obvious way of getting there.

[Andy-Grigg]

This is something that I've noticed when preparing the documentation of some new packages for release.

One quick fix is to add self to the toctree on the index.rst page, optionally with a custom name by doing something like Homepage <self>. The home link then shows up on each page in the top bar.

It's not a great solution though, since it's not a theme-level fix. It will require adding this to every index.rst file separately.

[akaszynski]

I would argue that for a user looking at a specific page, it's more important to get to the root of that project, instead of the PyAnsys page. At the very least, there should be an obvious way of getting there.

There was a request from ACE to have the top left "PyAnsys" icon return to docs.pyansys.com rather than the root page. It's a tradeoff between projects unity and connectivity as well as simplicity.

In my opinion, it's not obvious in the first place that the logo should even link to the home page, but an additional top level tab will take up extra space.

Open question: is there a way we can link to the main docs.pyansys.com page and permit users to also navigate back to the project home page. Pinging @PipKat for visibility and input.

[greschd]

I photoshopped some options for this:

1. add an explicit "path" to the top of the page:
   

2. add a link below the icon, (needs a thicker top bar):
   

3. add a "Home" menu entry (the current workaround):
   

[Andy-Grigg]

I like the path/breadcrumbs idea. That makes it clear where you are within the overall pyansys hierarchy and makes it easy to get back to a certain level.

[da1910]

I would agree, the breadcrumbs idea avoids the problem of defining "Home" or "Introduction", I think it makes sense for the navigation options to be in one place, rather than fragmented into a picture hyperlink and an ambiguous heading.

[Andy-Grigg]

I have spent a bit of time this afternoon looking into this. It looks like option 1 is very do-able with sphinx and it's something we could add to the theme, although we might have to hard-code the link to docs.pyansys.com in the package.

[greschd]

I have spent a bit of time this afternoon looking into this. It looks like option 1 is very do-able with sphinx and it's something we could add to the theme

Awesome! Option 1 would be my favorite, too.

although we might have to hard-code the link to docs.pyansys.com in the package

I think it's fine to have that hard-coded or configurable in conf.py, since it's anyway already hard-coded on the icon.

[Andy-Grigg]

It looks like it's possible to use the theme_logo_link property from conf.py in the jinja:

<a href="{{ theme_logo_link }}">pyAnsys</a>

If we're happy with this approach, I'll spend some time today playing with the CSS and getting a PR in for review.

[PipKat]

I like that approach as well!