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.

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

Jump to bottom

Initial docs restyling #2612

Merged
merged 4 commits into from Jun 13, 2018
Merged

Initial docs restyling #2612

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8b8b024
Include: custom stylesheet
medubelko Jun 12, 2018
be65ee7
Add custom stylesheet
medubelko Jun 12, 2018
a333d0e
Add script for grabbing logo files out of resources
medubelko Jun 13, 2018
847fd82
Add .gitignore for logos
medubelko Jun 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/source/_static/.gitignore
View file
Open in desktop
@@ -0,0 +1,2 @@
GafferLogo.svg
GafferLogoMini.svg
78 changes: 78 additions & 0 deletions doc/source/_static/gaffer.css
View file
Open in desktop
@@ -0,0 +1,78 @@
/* ===================================
CSS overrides for Gaffer documentation
==================================== */

/* Match regular nav background to Gaffer brand colors */
.wy-side-nav-search {
background-color: #343131;
}

/* Match mobile nav background to Gaffer brand colors */
.wy-nav-top {
background-color: #b92227;
}

/* Increase nav version color visibility */
.wy-side-nav-search > div.version {
color: inherit;
}

/* Add "Gaffer" in front of nav version (this sidesteps changing the Sphinx template) */
.wy-side-nav-search > div.version::before {
content: "Gaffer ";
}

/* Make nav search simpler and a little duller when not focused */
.wy-side-nav-search input[type="text"] {
border-width: 2px;
border-color: transparent;
background-color: lightgrey;
background-clip: padding-box;
transition: all 0.3s linear;
}

/* Transition search bar to white bg with Gaffer red border on focus */
.wy-side-nav-search input[type="text"]:focus {
border-color: #b92227;
background-color: white;
}

/* Make nav button color red on click */
.wy-menu-vertical a:active {
background-color:#b92227;
}

/* Increase font size for mobile header title */
.wy-nav-top a {
font-size: 120%;
}

/* Adjust the mobile menu button (and center-align mobile header title) */
.wy-nav-top i {
display: block;
position: absolute;
left: 15px;
top: 15px;
}

/* Add icon after external links */
a[href^="http"]:after {
content: " " url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAVklEQVR4Xn3PgQkAMQhDUXfqTu7kTtkpd5RA8AInfArtQ2iRXFWT2QedAfttj2FsPIOE1eCOlEuoWWjgzYaB/IkeGOrxXhqB+uA9Bfcm0lAZuh+YIeAD+cAqSz4kCMUAAAAASUVORK5CYII=);
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not sure how I feel about this one. None of the websites we're linking to use an icon for their links... is this considered standard?

Copy link
Contributor Author

@medubelko medubelko Jun 13, 2018 •
edited

Choose a reason for hiding this comment

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

It adds the standard external link icon () to indicate to the user they're being taken to an outside URL – not for internal doc links. It's a courtesy feature to improve UX. We won't be using external links often, in any case.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, I know. I'm just saying its a courtesy that none of the links on our main page (Arnold, Appleseed, 3delight, Tractor, Sphinx) are doing themselves for their external links, so I was wondering if that's modern standard UX or legacy from wikipedia days?

Copy link
Contributor Author

@medubelko medubelko Jun 13, 2018 •
edited

Choose a reason for hiding this comment

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

This will differ from the main site. They're still relevant and useful for most help files and docs.

Websites don't use them very often, because there's an understanding by the user that on the web (= multiple "documents," dynamic) most body text links are external references. In docs it's the opposite: most body text links are to other pages in the same help system (= single "document," static), and suddenly opening an external link can be jarring and disruptive. A more immediate use for this is that it will signal to IE users that they'll need to open that link in Isla.

A more complex way of accomplishing this is to use automatic hover-text, but this was the simpler and more direct method.

Copy link
Contributor

Choose a reason for hiding this comment

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

Ok, fair enough. Thanks for the explanation.

color: #2980B9;
}

/* Fix fallback image text vertically alignment when inline */
img {
vertical-align: initial;
}

/* Make nested and serial headers more distinguishable */
h2 {
margin-top: 2em;
padding-bottom: 0.25em;
border-bottom: 1px solid #e1e4e5;
}

h3 {
font-size: 100%;
}
13 changes: 9 additions & 4 deletions doc/source/conf.py
View file
Open in desktop
Expand Up @@ -121,7 +121,9 @@
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
html_theme_options = {
'logo_only': True
}

# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
Expand All @@ -135,7 +137,7 @@

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
html_logo = "_static/GafferLogoMini.svg"

# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
Expand All @@ -159,7 +161,7 @@

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
Expand All @@ -178,7 +180,7 @@
#html_split_index = False

# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
html_show_sourcelink = False

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
Expand Down Expand Up @@ -381,3 +383,6 @@ def setup( app ) :
app.add_transform( GafferTransform )

app.connect( "source-read", gafferSourceSubstitutions )

# Add the custom stylesheet; used in all .md and .rst files in source
app.add_stylesheet( 'gaffer.css' )
6 changes: 6 additions & 0 deletions doc/source/generate.sh
View file
Open in desktop
@@ -0,0 +1,6 @@
#! /bin/bash

set -e

cp ../../resources/GafferLogo.svg _static
cp ../../resources/GafferLogoMini.svg _static