executablebooks / sphinx-book-theme Goto Github PK

I think it might be helpful to add styling around executed outputs - maybe a cell that looks like the code input but lighter? I'm open to other ideas.

Also, some of the executed outputs are aligned in the middle. I think they should be aligned to the left, similar to the rest of the executed outputs.

Style for sphinx-tabs in sphinx-book-theme.scss reveals the border between the bottom of a tab and that tabs contents:

See sphinx-tabs README for expected style.

Relates to issues in jupyter-book and sphinx-tabs.

Describe the bug

When using :align: center with images (SVG) from a jupyter-book document (myst source file), the image remains aligned to the left.

I am able to overcome this by adding the following to my custom.css:

img.align-center {
   margin-left: auto;
   margin-right: auto;
   text-align:center;
   display:block;
}

I don't fully understand why this solution works, so I'm reluctant to submit it as a PR.

Environment
jupyter-book 0.7.3
Sphinx 2.4.4
sphinx-book-theme 0.0.33
sphinx-bootstrap-theme 0.7.1
sphinx-copybutton 0.2.11
sphinx-rtd-theme 0.4.3
sphinx-thebe 0.0.7
sphinx-togglebutton 0.2.0

You don't actually mention anywhere (in the docs or README) that its pip install sphinx-book-theme and html_theme = "sphinx_book_theme"!

I think pre-populating the issue description with the selected text would cover a lot of use cases, especially where the user wants to report a minor typo.

This is a follow-up from #118.

Is it possible to include things that aren't links in the TOC? we should figure that out...

This could probably be done by:

• Putting this feature in the CLI only (because it'll require a non {toctree} way to define book structure, like the YAML file!)
• Letting people put spacers (maybe other stuff) in the YAML TOC file
• edit this: https://github.com/ExecutableBookProject/sphinx-book-theme/blob/master/sphinx_book_theme/__init__.py#L33 to cross-ref things it finds with the YAML file and manually insert things like breaks ✨

iooxa has a nice component for displaying a TOC: https://iooxa.dev/article/outline

perhaps we could use that here for the same effect

Is your feature request related to a problem? Please describe.

• The (left) sidebar "comes in from the top" of the page, through resizing of the corresponding element. This implementation requires JS to work [^1] and shows up in a different place than the desktop sidebar.
• The (left) sidebar does not degrade gracefully when JS is disabled. A user who has JS disabled for some reason (ahem like me) cannot view documentation built with this theme on mobile, since the sidebar cannot be collapsed and covers regular content. And they can't access the navigation either.

A link to the documentation page where you see an issue.

Any page works TBH. Here's the page I have open right now: https://sphinx-book-theme.readthedocs.io/en/latest/index.html

Describe the solution you'd like

I suggest we switch to the same mechanism+design for providing the sidebar as the mkdocs-material theme: https://squidfunk.github.io/mkdocs-material/getting-started/. Try it on ~1024px wide windows, which shows how it works best IMO. That mechanism works without needing JS (it's pure-CSS) and, thus, degrades gracefully.

Note that I'm not suggesting we change the contents/design of what's in the sidebar in this issue, but only how it is handled in terms of being visible/not visible.

FWIW, I have experience with implementing this style of a sidebar, from when I was working on re-implementing mkdocs-material for Sphinx here. I'm happy to try re-implementing it in the context of this theme, if there's interest in making this switch.

It looks like the javascript for tooltips isn't being loaded

Is your feature request related to a problem? Please describe.

It is currently unclear to me (someone new to the project!) what I should do to work on this theme, and what workflows are for the various tasks related to the project.

A link to the documentation page where you see an issue.

N/A

Describe the solution you'd like

A clear "Development/Getting Started" guide (like https://pip.pypa.io/en/latest/development/getting-started/) that describes how to setup a development environment, and how to do common development workflow tasks -- namely running the code, generating the documentation, running linters, running the tests.

I suggest using something like nox, to simplify the workflow tasks even further, to be "run nox -s <name>". Being able to do nox -s lint / nox -s docs / nox -s tests and having it manage setting up the environments, would be great. Once I figure out what the setups look like, I'd be happy to file a PR adding a nox configuration for this project, if it would be welcome. :)

Since yesterday, my documentation has been broken with the following error:

writing output... [ 14%] api/modules
Theme error:
An error happened in rendering the page api/modules.
Reason: TypeError("'NoneType' object is not callable")
make: *** [html] Error 2

It's in the templated API page, but that used to work and works in RtD's theme. Forcing the version to 0.0.30 solves the issue. It's in boost-histogram.readthedocs.io / GitHub.com/scikit-hep/boost-histogram.

It asks for github_version in html_context but really needs to be repository_branch. Also should probably just default to master.

Also, path to docs should just default to the Sphinx docs build folder

Description

We currently only support GitHub repositories for "repository link" as well as "edit this page". We should support a few of the more common ones as well, such as bitbucket and gitlab.

Here are major repository-specific features we'd want to implement:

• Repository link / issues link
• Edit this page link
• Launch buttons link

Benefit

This would make these theme features usable for people that use these other (quite popular) platforms!

Implementation details

Repository link

For the repository link, here's our code (and likely where a fix would be):

https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/topbar/repobuttons.html

Edit this page link

We seem to be using the PyData Sphinx Theme get_edit_url function for this already, so we should figure out how to make it support non-GitHub repositories:

here's the PyData theme function for this:

https://github.com/pydata/pydata-sphinx-theme/blob/055ae27cdc6801d6abba0c43bfa9cfd3a359e1b9/pydata_sphinx_theme/__init__.py#L481

launch buttons

Here's the templating for our launch buttons:

https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/topbar/launchbuttons.html

And the Python logic that handles how we build these buttons:

https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/launch.py

Maybe we can re-use the get_edit_url for this somehow as well.

This would require changes here and here.

In particular raw git remotes should cover a lot of use cases.

Is your feature request related to a problem? Please describe.

Font sizing changes in the sidebars make it difficult to read/skim the sidebar's contents and well as make it look out-of-place.

Describe the solution you'd like

Use the same size as the content for all navigation items in both sidebars.

• The indentation is sufficient to make the "depth" clear.
• Whitespace + bold text can be used for captions and toctrees to separate them visually.

See readme.com's design for inspiration/idea.

Describe alternatives you've considered

I can't think of any good ones. :)

Additional context

I'm happy to try implementing this myself, if there's interest in this idea. :)

Per some comments from @chrisjsewell we should add:

• Less whitespace to the left in single page mode (closed by #104)
• The option to keep the TOC present at all times (now in #102) closed by #103

(longer term we can try to find a way to put the TOC in the left sidebar, but for this will at least improve things for now)

In many of the tests we are just seeing if some text made it into the HTML at all. That usually works, but it'd be better to zero-in on the specific part of the page we want to test and use beautifulsoup to confirm what is in there

In a conversation with @ericvd-ucb he brought up a use-case I have heard many others mention as well, which is that they'd like to have a website that hosts multiple books, and want some way to link between books on their site. This is an issue to figure out that use-case.

Two options I can think of:

• Make it easy to add extra links to the book's navigation in the sidebar. Maybe with a specific configuration value, or a way to parse toc.yml to find this.
• Make it possible to add a top-bar (similar to the pydata one?) that can link between books or other external pages.

Describe the changes you'd like

Title says it all.

Describe alternatives you've considered

None. Status quo is OK. Suggested change is nicer, but I'm obviously biased. :)

Additional context

This seems to be the phrasing for the in-page-navigation-tree on all 3-column documentation-oriented themes that I know of (except this theme and the pydata theme). Sample Screenshots: https://gist.github.com/pradyunsg/eeb74ac5b580d502c3d0e248310f273f

I'm happy to file a PR for this, if there's interest in this idea. :)

The binder button in the local html files points to this binder_url: https://mybinder.org/v2/gh/ExecutableBookProject/cli/master?filepath=/docs/*.ipynb.

cli should be the replaced with the updated org var. From what I can tell add_binder_url() in sphinx_book_theme/__init__.py works fine.

(migrating from #80)

In Safari, bringing your cursor over "On this page" results in the menu appearing and then disappearing, before one has a chance to click on anything (or read it really). On Firefox, it seems to have the desired behavior (menu appearing when highlighted, staying until you click or move elsewhere).

Currently the right TOC will hide itself when you scroll down the page, but this probably doesn't make sense for Sphinx themes which generally don't use the right margin as much (as opposed to Jupyter Books which may use this more).

We should either:

1. Make the "hiding" functionality of the right toctree and option
2. Only make the right toctree hide on scroll if there is margin content on the page

Is your feature request related to a problem? Please describe.

Content at the top of the page gets cropped, seemingly for no reason.

Describe the solution you'd like

A shadow underneath the top bar would make it easier to perceive that there is an element that's supposed to be on top, making it clearer why content is getting cropped (there's something above it!).

Describe alternatives you've considered

None.

Additional context

See https://squidfunk.github.io/mkdocs-material/getting-started/ for a decent+subtle implementation of this.

Describe the bug
I have noticed a bug when navigating the following url from an iPad: https://jupyterbook.org/intro.html.

The menu is displayed like grayed/transparent on top of the text, and it doesn't look good at all.

To Reproduce
You may navigate to the url above from an iPad, or just use chrome developer tools and select iPad.

I have copied below a screenshot showcasing the issue and how to reproduce it.

Hope it helps!

It would be great if we had hover-style citations similar to how Distill does citations (example). When a user hovers over a citation, a short pop-up shows the reference for that citation.

I wonder if that's something that could be shared between @rowanc1's projects and jupyter book? Even better if we could upstream this to sphinxcontrib-bibtex.

Maybe there is a <citation> web component that is becoming a standard these days?

It is nice and easy to turn any Jupyter notebook on GitHub into an executable one on Colab by simply visiting any URL of the form https://colab.research.google.com/github/USER/REPO/blob/master/PATH/FILENAME.ipynb. This is often more desirable than Binder because of the much faster load time of the Colab environment than the Binder one, and of course the ability to save your own copies of notebooks. Could this be an option in jupyter-book, at least for those books published to GitHub?

• glossary CSS: https://sphinx-book-theme.readthedocs.io/en/latest/reference/markdown_limits.html#glossary
• sidebar CSS: https://sphinx-book-theme.readthedocs.io/en/latest/reference/demo.html#sidebar
• open graph metadata tags
• testing suite: https://github.com/ExecutableBookProject/sphinx-book-theme/blob/master/tests/test_build.py

Hi!

First of all, I would like to congratulate all of you for the great work done with this theme. It looks great!

I have read that, somehow, it is inspired in Pandas theme, used here: https://pandas.pydata.org/pandas-docs/stable/

I personally like a bit more Pandas theme than the current proposal from jupyterbook, and I was wondering how difficult is to have the same theme as Pandas, if possible.

Any guidance about how to get it done would be welcomed!

In the meanwhile, have an awesome day!

Regars,
Miguel

We've made a few changes lately that I think make the theme more a11y-friendly, which is good. Though they also seem to have crowded things a bit when there is a lot of text on the screen. For example, here's what the EBP contributing page looks like in this theme:

New version

Old version

Maybe this is just me, but it feels more "crowded" and text-heavy now. I'm not sure what's the best way to improve this 🤔 maybe @pradyunsg has thoughts

This is intended to initiate a discussion, to gauge whether there's anyone else who feels such a change would be useful as well as figure out what we'd change to. :)

Describe the change you'd like

Multiple changes to the design of the bottom-of-page in this theme:

• Add a bit of space to separate "content" from "footer"
• Change the content in the footer (making it similar to the left half of mkdocs-material's bottom-of-page)
  • Move "Theme by the Executable Book Project" out of the left sidebar, into the footer
    • This is a more visible spot, and it's still out-of-the-way enough :)
  • Tweak the copyright line to match what most other documentations themes do
    • "Copyright © 2020 <project name>"
• Change how the next/previous links look
  • Swap "<<" and ">>" for proper arrows
  • Limit width to the content (instead of overflowing into right sidebar's region)
  • Tweak style to be a middle-ground between what GitBook and mkdocs-material do
    • 50% width for both "next and prev" (like GitBook)
    • Align text to be closer to the arrows (like mkdocs-material, maybe?)
    • No visual border around the element, but a general region around the text works (like mkdocs-material, maybe?)

Additional Context

(screenshot of current bottom of page)

(screenshot) GitBook's bottom-of-page:

(screenshot) mkdocs-material's bottom-of-page:

readme.com's bottom-of-page (screenshot, click to view)

Top-of-page screenshots and links to the corresponding pages: https://gist.github.com/pradyunsg/eeb74ac5b580d502c3d0e248310f273f

A few attempts at making the middle "main content" section grow automatically haven't worked, because it expands to fill the extra space due to the wide elements inside of it. We should figure out how to get around this, so that we only need to define the width of the left and right sidebar, and have the middle column automatically expand

Currently the theme uses superscripted citations which look like this:

@jstac suggested that we remove the superscript. What do folks think about displaying citations inline with text similarly to how they're displayed below?

cc @choldgraf @chrisjsewell @mmcky @AakashGfude in case you have thoughts about this.

One of the important use cases for incorporating thebelab into a project is to allow tweaking already existing outputs. Out of the box, IIUC the already computed outputs would be duplicated by whatever thebelab produces.

At the same time, thebelab supports specifying predefined arguments, which are made into cell outputs as soon as thebelab is activated, see the required config here.

This would require modifying thebelab configuration, as well as ensuring that DOM is appropriate (the outputs must be in a div that directly follows the input).

See https://www.w3schools.com/tags/tag_dl.asp

This means, for example, sphinx API documentation looks rubbish, because there is no delineation between components, e.g.

• RTD theme: https://ipypublish.readthedocs.io/en/latest/api/ipypublish.convert.main.html
• book theme: https://markdown-it-py.readthedocs.io/en/latest/api/markdown_it.main.html

I propose to allow making some toc sections collapsible and collapsed by default.

While the default works well, collapsible toc sections would be potentially useful for appendices/exercise solutions (my personal use case)/bonus chapters.

Edit: readme.com has a good example of collapsing entries in the section-pages-tree (left sidebar):

In my book as well as in the documentation if you click to download the source of a jupyter notebook in the upper right button, it seems to add a .txt extension to the .ipynb file. I'm not sure if this is by design or a bug, I looked quickly and could not find it documented.

In the same documentation, there is a html link: "you can download the notebook content for this page." that results in downloading a notebook file (.ipynb) fine.

Hi guys!

This is very cool what you are building! 🙂 I was wondering that how do you see the future of sphinx-book-theme? I.e. is the idea to eventually support all the same functionalities that Jupyter Book has now or how are these projects related?

We are writing a book with my colleagues and originally we have been using Sphinx to build all our materials. Then we found Jupyter Book and seriously started thinking switching to that one because of many cool features (such as the interactive code cells with Thebelab). I was already playing around with the JupyterBook a bit and configuring the pages with RTD (not very straightforward..), and then I found this theme! So again I am wondering that should we stick with Sphinx and wait this project to develop.. 😄

@choldgraf

Thebelab

add button to code cells: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/js/thebelab-cell-button.html

page config: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/js/thebelab-page-config.html

master script: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/js/thebelab.html

button: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/buttons/thebelab.html

JupyterHub

Button code: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/buttons/jupyterhub.html

page in old docs

https://beta.jupyterbook.org/old_docs/features/interact.html

Readers of the documentation searching for a nice sphinx theme and not familiar with MyST may be confused by the MyST code examples and its relation with restructured text. Perhaps it's worth to clarify this.

Is there a reasoning for this? Don't know if I like it 😬

I say this because I've been playing around with overriding the RTD theme admonition icon with custom ones for different semantic content e.g.

.title-icon-troubleshoot .admonition-title:before {
    margin-right:.5rem;
    content: "\f0ad"  /* wrench */
}
.title-icon-read-more .admonition-title:before {
    margin-right:.5rem;
    content: "\f08e"  /* external-link */
}

.. admonition:: Having problems?
    :class: attention title-icon-troubleshoot

   ...

I don't think this would look as nice with icons after.

This is a continuation from #114, following #118.

Several places now hard-code github-specific information. For example #118 introduces the github icon in the top bar, and the schema for pre-populating issue with parameters.

I realize that github is the main priority for this project, however I'd like to know:

• If support of other repository types is on the roadmap?
• What would be the most reasonable way to configure this?

For example if one wanted to adjust #118 to support bitbucket or gitlab, they would need to make the repository icon customizable (instead of fa-github), and change the schema for pre-populating the issue title and description. This is all doable, but I'd like to know how would the user control it? Would there be a single "repository_type" configuration key?

As with pydata/pydata-sphinx-theme#180, but more acute because the right "on this page" section seems to disappear as you scroll down the page: https://sphinx-panels.readthedocs.io/en/sphinx-book-theme/?

The lightgrey vertical line in this blockquotes does not render locally or in the published version.

Could use PrintJS like in Jupyter Book:

https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/_includes/js/print.html

Describe the change you'd like

The change would be to move topbar icons into the right sidebar, similar to how GitBook handles the "Edit on GitHub" button.

IMO, the right sidebar and left sidebar feel a little asymmetric in terms of the amount of content they hold. This would allow for balancing the amount of content on top of both the sidebars, while still providing the same functionality (with potentially text descriptions, if we decide to add them as an annotated list instead of as-is icons).

Describe alternatives you've considered

Maintain status quo. Or, add full-width top bar or something similar that's visually distinct from the rest of the content.

Additional context

I'm happy to try implementing this myself, if there's interest in this idea. :)

If the top toctree only has sub-directory index files, then we work fine

However, if there are also other top-level files, this breaks things w/ a theme error, we should figure out what's up

I use macOS 10.15.4 Catalina.
In this link, Safari 13.1 does NOT show the content of the On this page navigation menu at the top-right corner, whereas Firefox 75.0 and Chrome 81.0 do show it if the mouse cursor hovers over On this page.

[EDIT]
I also tried Safari on iPad Pro with iOS 13.4.1. The same problem as in Safari on Mac.

I'm seeing some awkward clipping behavior on mathjax embeds in Figure captions. In Firefox, I see this:

which is generated by the following markdown:

```{glue:figure} shifting

*Left*: an impulse (top), a negative impulse (middle), and a 3-step delay (bottom).
*Middle*: the DFT spectrum (real and imaginary) components of each signal are distinct.
*Right*: all three signals have identical magnitude spectra $|X[m]| = 1$.
```

Note the truncated math span for $|X[m]| = 1$.

In Chromium, I see this:

which is at least not truncated, but the scaling seems incorrect to me.

(NB: I have some custom CSS to do justified text layout, but that's independent of this problem.)

The problem appears to come from a bad interaction between the book theme and mathjax due to setting font-size: 0.9em here

This appears to be fixed if I hack this in the console to scale up to font-size: 0.9rem (root scaling). It then renders as (in Firefox):

and in Chromium:

In both cases, the surrounding typesetting seems .... broken (note the unpredictable placement of the following punctuation). I'm not enough of a CSS wiz to sort that one out. EDIT: I think this one might be down to mathjax.

This problem may pop up in other places, and it's probably worth doing a thorough audit to ensure that root scalings are used where appropriate.

The command-line interface might want to trigger behavior that changes the buttons that are present, we should figure out how to make this extensible

Right now, the sidebar pops up at a certain width and crowds the main content. I'm not sure whether this is ideal, we should figure out the right way to include sidebar content without wasting (or crowding) space.

Another option would be to have the sidebar overlap with the TOC, and figure out some way to prevent them from clashing in uncomfortable ways.

This is also related to having a "full-width" figure a-la Tufte, because some pages may have right sidebar white-space while others may not

An approach that mimics Jupyter Book:

• Start off in-line
• At a medium breakpoint:
  • sidebar items moves from inline to right-sidebar
  • width of content stays at 100%
  • The TOC also shows up, but it only shows on hover
• At an xl breakpoint:
  • width of content moves down to ~70%
  • sidebar now takes up the extra 30% that's there
  • TOC content is shown all the time

Describe the bug
Text marked with <strong>...</strong> (obtained by **...** in Markdown in jupyter-book) looks just like regular text.

To Reproduce
Steps to reproduce the behavior:

1. Surround some text in a jupyter-book project with double asterisks.
2. Compile the project to a book.
3. Visit the generated website in the browser.
4. Notice that the marked text does not appear different from the surrounding text.
5. Inspect the text using the browser's developer tools.
6. Note that, while there are indeed <strong>...</strong> tags around the text.

Expected behavior
Strong text should appear emphasized, typically using bold.

The screenshot below was generated from the following Markdown:

## Functions

**Definition:** A *function* is any method for taking a list of inputs and determining the corresponding output.

Environment (please complete the following information):

• Python Version 3.7.3
• Output of pip show jupyter-book says the version is 0.7.0b4.dev0