Skip to content

Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) #10039

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Feb 17, 2023
Merged

Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) #10039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea11659
Move emojis in front of TOC captions, use a CSS ::before rule for add…
benjaoming Feb 16, 2023
57ff576
Fix a JS error when there is no "hash" found
benjaoming Feb 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/_static/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,15 @@
#rtd-stickybox-container {
text-align: center;
}

.wy-menu.wy-menu-vertical a.reference.external::after {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd argue for this on all external links, but baby steps :)

Though @humitos had a good point that it makes the link more visible, but I think it's good to be explicit here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

Though #10026 (comment) that it makes the link more visible, but I think it's good to be explicit here?

The font-awesome icon is much more discreet so I think that it works better.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get a feeling that this will cause unintended side-effects.. like if the <a> is on an <img> tag

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, we likely need to scope it smartly. I'm sure there's good examples of doing this other places, but we can start w/ the toctree for now.

/* \00a0 = no break space */
content: "\00a0\f08e";
font-family: FontAwesome;
display: inline-block;
font-style: normal;
font-variant: normal;
text-rendering: auto;
-webkit-font-smoothing: antialiased;

}
24 changes: 13 additions & 11 deletions docs/_static/js/expand_tabs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,19 @@ $( document ).ready(function() {

// Uses a hash referencing a Sphinx label from the URL page#sphinx-label
var hash = window.location.hash.substr(1);
hash = hash.replace(/[^0-9a-z\-_]/gi, '');
// If the hash is inside a tab panel
var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel");
if (hash) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What changed in this file? Seems like it needs a comment.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The git diff is awful, it was just a matter of adding if (hash) { to fix a JS error occurring on all pages.

It's explained in line 22, the following code is pretty verbose:

// Uses a hash referencing a Sphinx label from the URL page#sphinx-label
var hash = window.location.hash.substr(1);
if (hash) {
...

hash = hash.replace(/[^0-9a-z\-_]/gi, '');
// If the hash is inside a tab panel
var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel");

if (tab_with_reference.length > 0) {
// Use the panel's ID to guess the tab's ID
var panel_id = tab_with_reference.first().attr("id");
var tab_id = panel_id.replace("panel-", "tab-");
// Invoke the tab buttons click() method to display it
$("button#" + tab_id).click();
// Scroll the tab widget into view
$('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000);
if (tab_with_reference.length > 0) {
// Use the panel's ID to guess the tab's ID
var panel_id = tab_with_reference.first().attr("id");
var tab_id = panel_id.replace("panel-", "tab-");
// Invoke the tab buttons click() method to display it
$("button#" + tab_id).click();
// Scroll the tab widget into view
$('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000);
}
}
});
10 changes: 5 additions & 5 deletions docs/user/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Read the Docs: Documentation Simplified
.. toctree::
:maxdepth: 2
:hidden:
:caption: Tutorials 🚀
:caption: 🚀 Tutorials

/tutorial/index
/intro/getting-started-with-sphinx
Expand All @@ -15,7 +15,7 @@ Read the Docs: Documentation Simplified
.. toctree::
:maxdepth: 2
:hidden:
:caption: Explanation 💡
:caption: 💡 Explanation

/choosing-a-site
/integrations
Expand All @@ -27,7 +27,7 @@ Read the Docs: Documentation Simplified
.. toctree::
:maxdepth: 2
:hidden:
:caption: How-to guides 🪄
:caption: 🪄 How-to guides

/guides/authors
/guides/administrators
Expand All @@ -37,7 +37,7 @@ Read the Docs: Documentation Simplified
.. toctree::
:maxdepth: 2
:hidden:
:caption: Reference 📚
:caption: 📚 Reference

/reference/features
/config-file/index
Expand All @@ -48,7 +48,7 @@ Read the Docs: Documentation Simplified
/api/index
/changelog
/about/index
Developer Documentation 🔗 <https://dev.readthedocs.io>
Developer Documentation <https://dev.readthedocs.io>

.. meta::
:description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs.
Expand Down