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: adapt source for single-page HTML build #7

Conversation

sadielbartholomew
Copy link

Suggestions for amendments to cylc#2970 (& sibling cylc#2971). Let me know if you disagree with anything!

Context:

  • Table of Contents: within the single page, including at the very top, it has disappeared & in the sidebar it does not expand to nested levels upon clicking, as in the multi-page build. This appears to be a known Sphinx issue (missing index in singlehtml output sphinx-doc/sphinx#3631) so all that can be done here is to hide (:eight_spoked_asterisk:) the explicit heading "Table of Contents:" in the top title element.
  • Blank areas: when converting the docs towards a multi-page HTML I added some vertical whitespace onto the end of pages with little content to prevent the footer from being so high it overlapped the contents listing in the sidebar. This is now showing up as blank areas in the single-page build, e.g. under 4.2. Cycle Points. In my PR these are not included into (:eight_spoked_asterisk: ) the singlehtml build.
  • Flash on scrolling: The page flashes black on a fast scroll up/down the page, at least as I see it. I had a play & it seems it flashes to the colour set as the background colour to the footer. I doubt there is much we can do about the flashing (due to too much content to load over a short time period I imagine), but to make it less obvious/painful & even cut any risk of giving an epileptic a seizure, we can make it flash to white to match the page background colour. The footer doesn't then match the top & bottom bars but I can live with that.

✳️: Sphinx has a handy only directive which can be used to insert content only given certain tagged conditions, including on a per-build basis via .. only:: builder_<builder>.

@hjoliver hjoliver merged commit 86f4b2a into hjoliver:sphinx-doc-single Feb 27, 2019
@sadielbartholomew sadielbartholomew deleted the sphinx-doc-single-additions branch April 3, 2019 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants