Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add way to select version for documentation #53317

Draft
wants to merge 2 commits into
base: devel
from

Conversation

Projects
None yet
5 participants
@Akasurde
Copy link
Member

Akasurde commented Mar 5, 2019

SUMMARY

Signed-off-by: Abhijeet Kasurde akasurde@redhat.com

ISSUE TYPE
  • Docs Pull Request
  • Feature Pull Request
COMPONENT NAME

docs/docsite/_themes/sphinx_rtd_theme/versions.html
docs/docsite/rst/conf.py

docs: Add way to select version for documentation
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

@Akasurde Akasurde requested review from acozine , gundalow and samccann Mar 5, 2019

@Akasurde

This comment has been minimized.

Copy link
Member Author

Akasurde commented Mar 5, 2019

After merge this might look like this -

screen shot 2019-03-05 at 4 24 35 pm

@ansibot

This comment has been minimized.

Copy link
Contributor

ansibot commented Mar 5, 2019

Fix alignment of ethical-ad section in navigation bar
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
@dagwieers
Copy link
Member

dagwieers left a comment

LGTM, but

  1. The version selection should be at the top just below the title but above the search form (the screenshot seem to indicate the version is at the very bottom ?)
  2. The title currently has in big Ansible and then below to the right devel or latest. This has always bothered me, it looks like a visual bug. Maybe the pull-down could be combined with the version in the title to show the current version, so it doesn't have to be in the title really.
  3. In fact, if we put at the top "Ansible documentation", there is no need to have Ansible or devel below, and we can simply show the current version in the drop down so people can easily select a different one.

screenshot from 2019-03-05 13-54-00

{% else %}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book">Ansible Version docs</span>

This comment has been minimized.

@dagwieers

dagwieers Mar 5, 2019

Member
Suggested change
<span class="fa fa-book">Ansible Version docs</span>
<span class="fa fa-book">Ansible documentation:</span>

This comment has been minimized.

@Akasurde

Akasurde Mar 5, 2019

Author Member

OK.

This comment has been minimized.

@samccann

samccann Mar 5, 2019

Contributor

I'd like to keep 'version' in the name here... so maybe "Ansible documentation versions:" ?

@ansibot ansibot removed the needs_triage label Mar 5, 2019

@Akasurde

This comment has been minimized.

Copy link
Member Author

Akasurde commented Mar 5, 2019

  1. The version selection should be at the top just below the title but above the search form (the screenshot seem to indicate the version is at the very bottom ?)

I am using native sphinx-rtd-theme implementation of showing versions like - https://sphinx-rtd-theme.readthedocs.io/en/stable/
But we can implement this idea as well.

  1. The title currently has in big Ansible and then below to the right devel or latest. This has always bothered me, it looks like a visual bug. Maybe the pull-down could be combined with the version in the title to show the current version, so it doesn't have to be in the title really.

Yes. I agree.

  1. In fact, if we put at the top "Ansible documentation", there is no need to have Ansible or devel below, and we can simply show the current version in the drop down so people can easily select a different one.

I can try this as well. Will wait for other people to comment.

@dagwieers

This comment has been minimized.

Copy link
Member

dagwieers commented Mar 5, 2019

I made a mock-up, but I do not really like it. (Too dark, not a pull-down, too condensed)

screenshot from 2019-03-05 14-20-54

What I would like to have is

  1. Versions: on the left
  2. A pull down to the right that shows the current version, but you can select another version
  3. Select another version should bring you to the same URL with the version substituted, so not to the index of the documentation (as that is not really helpful)
  4. If that page would not exist, we should have a fancy 404 page with a search box (possibly prefilled with keywords from the URL) and an easy way to go back
{% else %}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book">Ansible Version docs</span>

This comment has been minimized.

@samccann

samccann Mar 5, 2019

Contributor

I'd like to keep 'version' in the name here... so maybe "Ansible documentation versions:" ?

@@ -240,3 +240,9 @@
intersphinx_mapping = {'python': ('https://docs.python.org/2/', (None, '../python2-2.7.13.inv')),
'python3': ('https://docs.python.org/3/', (None, '../python3-3.6.2.inv')),
'jinja2': ('http://jinja.pocoo.org/docs/', (None, '../jinja2-2.9.7.inv'))}

html_context = {
'current_version': '2.7',

This comment has been minimized.

@samccann

samccann Mar 5, 2019

Contributor

What's the impact if we have 'current_version': 'latest' (so presumably we don't have to change that line ever?)

@samccann

This comment has been minimized.

Copy link
Contributor

samccann commented Mar 5, 2019

For @dagwieers markup - I don't think we can put Ansible documentation in the black bar at the top because that's the same bar that's used for tower and lint and network documentation.While I agree that the Ansible and devel in the current teal? box looks a bit wonky, it's important to keep that information visible 'somehow' - The same box can say Tower or Ansible or Lint, and it's important to make the version obvious.

I'm less fond of the list of versions in that markup ([2.5][2.6] etc) vs @Akasurde approach.

My suggestions:
1- Leave the top black bar as it is today ( Documentation)
2 - in the teal box - Keep Ansible and the version (though experiment with better ways of showing it)
3 - move that version section into the teal box, as dag suggested

@dagwieers # 3 above (making the version switch keep the same URL as whatever page you are on) would also be good. The fancy 404 is a separate fix imo.

@acozine acozine referenced this pull request Mar 11, 2019

Open

Docs meeting agenda #389

@acozine

This comment has been minimized.

Copy link
Contributor

acozine commented Mar 13, 2019

Example of a site that updates from old_version/my_page.html to latest_version/my_page.html: http://docs.citusdata.com/en/v8.0/installation/multi_machine.html

@ansibot ansibot added the stale_ci label Mar 13, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.