nengo / nengo-sphinx-theme Goto Github PK

Users don't need to see/interact with that dropdown very often, so we can "hide" it a bit by putting it at the bottom (and thereby feature the sidebar table of contents content more prominently).

On my screen, if I make the chrome window half screen (i.e. snap to the right side of my widescreen monitor), then the sidebar disappears.

My monitors are 1920 x 1080, so a window of ~960 x 1080 has no sidebar (I'm not sure how wide my vertical launcher task bar is on the monitor)

Just noticed that we accidentally reverted #5 at some point, probably when switching to the new theme.

One slightly annoying part of the Nengo Loihi docs is that we have to change several strings in the documentation when the NxSDK version changes. It would be nice if instead that version number could be part of the conf.py file, or some other location, and substituted in so that it's always updated everywhere, and updated easily.

ReST / Sphinx has the ability to replace text (see http://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html#substitutions) but this does not work inside code blocks. Here is a quick Sphinx extension to do it; we should add that extension (with a few minor tweaks) to Nengo Sphinx Theme and use it where appropriate.

From nengo/nengo-spa#214:

• Still uses Arial which I find less legible than Lato given that many of the SPA documentation pages have quite a lot of text.
• This might be purely my preference: But the new theme uses Courier for code instead of Menlo. I find the latter to be a much nicer font.
• The heading font is too large for some of the longish page titles in the SPA documentation (e.g. this one gets broken across four lines, though maybe some of the titles should be shortened)
  • The underscore in nengo_spa on the linked example hangs too low/doesn't work well with the given line spacing.
• The code width does not fit an 80 character line (though the textwidth is fine and should not get too wide either).
• If the navigation on the left is cut-off it only scrolls once your close to the end of the page. In the old theme it would scroll immediately independent of the scroll position of the main body.
• API pages in the old theme are better structured. There you can see at a glance where a new element starts thanks to the blue background of the heading. The new theme doesn't have such highlights and the member elements of a class look the same. Furthermore, there are two awkward boxes (one around nengo_spa. and one around the documented element).
• The tables with “Further members” for the nengo_spa main module API documentation don't look great. the description column on the right is too narrow.
• It is not clear wether the “See also” box for the ActionSelection class belongs to that class or the thalamus member because the shape of the octagon makes it look indented (while it is not).
• There is an awkward line break in “return type” in the documentation of methods.

The crate theme uses all-caps for the top-level heading on each page. I find this can be kind of difficult to parse when we have headings that use mixed capitalization. For example, when I read "NENGODL" I can't help but see "NEN-GOD-L". I'd argue that it doesn't work great for crate either (e.g. "CRATEDB" -> "CRATED-B" https://crate.io/docs/crate/reference/en/latest/). I could just add a space to separate things (e.g. "NENGO DL"), but that is something we're going to have to think about and remember for all headings on all projects. My inclination would be to use normal capitalization in the headings, if no one has a strong preference for the all-caps.

The previous theme had a search box which can be useful, but I do not see this theme to have such a functionality. (Also see nengo/nengo-spa#215.)

E.g., if you scroll through https://www.nengo.ai/nengo-dl/reference.html#developers you'll notice that the highlighting gets stuck on "Operator builders".

There is a lot of extra space inside the sidebar border at the bottom underneath the entries, not sure what the purpose of this is?

Example: https://www.nengo.ai/nengo/search.html?q=Ensemble

JS Console:

Other examples with similar (or sometimes the same) errors:

• Connection
• PES
• Learning
• Uniform
• tuning
• gain
• nengo

Examples that are fine (no error):

• asd
• q
• dt

Similar symptoms for nengo-loihi. Have not checked any others users of nengo-sphinx-theme.

Rather than statically copying the logos in each project repo.

Right now it still tries to render an image but the link is to None.

In documentation (e.g. Dist.sample) rng=np.random gets rendered as a pretty long and unhelpful string.

It would be nice if that rendered as something considerably shorter, like just np.random. I'm not sure how easy that would be to achieve, but it might be possible with a bit of Sphinx hacking.

Alternatively, we could modify Nengo core (and other projects) such that a module is never an argument default. We would switch it to be None and then do a np.random if None kind of thing.

The 4th level headings have a light gray font colour making it difficult to read against the white background colour of the page.

Image:

It probably should go to the instructions for the currently viewed subproject?

Something that's come up several times in Nengo core is that we can't use autoautosummary in situations where we want the user to use an object in a module that it's not originally defined in. For example, we want users to do something like nengo.Ensemble(neuron_type=nengo.LIF()) even though Ensemble is actually nengo.ensemble.Ensemble and LIF if nengo.neurons.LIF.

It would be nice to have a way to still use autoautosummary (so new objects aren't missed) but still be able to ensure that certain objects are referred to by our preferred name.

The highlight of the active fragment (when using a link to a subsection) renders a white box over the background which looks slightly weird when is is high enough on the page to cover green-blueish curve.

Example link

The width of logos might vary significantly depending on the project. It would be good to be able to configure the desired width in conf.py.

Links created by sphinx references have a smaller font size than normal (compared to regular links or other text).

For example:

Some documentation pages, like pytest-plt's, are short enough that they can/should be one page documents. Some changes that we should make to support this in nengo-sphinx-theme:

• Make an alternative to sidebar.html that uses the local TOC (.. contents::) rather than the global toctree

Any other ideas, please suggest here.

Right now it is possible to change the depth of the sidebar by setting sidebar_toc_depth (see https://github.com/nengo/nengo-sphinx-theme/blob/master/nengo_sphinx_theme/theme/sidebar.html#L52). Sometimes, specifically for changelogs it's convenient to set the depth of the sidebar on a page to be different from the global site setting. It should be relatively straightforward to do this on a per-page basis.

When there is a large/expanded ToC in the sidebar, the bottom of it may not be visible. The sidebar does not scroll to allow the user to view the bottom of the ToC. The only option for the user is to click another page in the sidebar to make the ToC smaller.

Browser: Chromium: Version 80.0.3987.163 (Official Build) Built on Ubuntu , running on Ubuntu 18.04 (64-bit)
Confirmed in Firefox 75.0

Spotted when linking to the docs on this Nengo forum post.

To reproduce on Chrome Version 78.0.3904.108 (Official Build) (64-bit):

• Visit https://www.nengo.ai/nengo/frontend-api.html#nengo.Network
• Observe that the position of the screen is not aligned with the position of the anchor

e.g., the nengo.Network anchor

looks like:

should be:

This appears to apply to any part of the documentation that is generated from a docstring. This does not appear to apply to anchors elsewhere (e.g., this anchor is fine). This effect appears to be independent of screen width.

With nengo_sphinx_theme.ext.renamed_autoautosummary, the [source] links for nengo_sphinx_theme.ext.renamed_autoautosummary.a_test_function and nengo_sphinx_theme.ext.renamed_autoautosummary.TestClass do not appear.

This is related to the following error that appears in the docs build output for this repo:

Traceback (most recent call last):
  File "/home/eric/venv/full3/lib/python3.6/site-packages/sphinx/ext/viewcode.py", line 35, in _get_full_modname
    return get_full_modname(modname, attribute)
  File "/home/eric/venv/full3/lib/python3.6/site-packages/sphinx/util/__init__.py", line 331, in get_full_modname
    module = import_module(modname)
  File "/home/eric/venv/full3/lib/python3.6/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 994, in _gcd_import
  File "<frozen importlib._bootstrap>", line 971, in _find_and_load
  File "<frozen importlib._bootstrap>", line 953, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'nengo_sphinx_theme.ext.renamed_autoautosummary'
viewcode can't import nengo_sphinx_theme.ext.renamed_autoautosummary, failed with error "No module named 'nengo_sphinx_theme.ext.renamed_autoautosummary'"

This does not appear to be a problem e.g. in the Nengo docs, when we rename classes like nengo.neurons.LIF to nengo.LIF. The difference could be that there we're renaming a single class, whereas here we're renaming a module.

(Feature request)

I find it very useful when the docs link directly to GitHub. This allows you to easily do things like click on the function calls in the body, check the history of the file, navigate the directory, etc. For example: nengolib.synapses.LegendreDelay has a [source] link in the top-right corner that takes you directly to the function, tagged by the appropriate version. NumPy and SciPy do the same. I make use of this regularly (and find myself regularly wanting this feature for Nengo docs as well).

The way this is done in nengolib is through the sphinx.ext.linkcode plugin, with a borrowed linkcode_resolve implementation.

Right now the top and sidebars are statically positioned in the page, so if you scroll down they both disappear and the only way to navigate to a different page is to scroll back up to the top. Personally I like having the navbars be floating/sticky, so that they're always present no matter where you are on the page. I could also see an argument for only having one or the other be sticky though?

The current width is slightly too small to render code with our standard character limit (e.g., see https://www.nengo.ai/nengo-dl/_modules/nengo_dl/simulator.html#Simulator).

Right now, it's possible to pass an empty string or a list with an empty string to the releases command line option and nengo-sphinx-theme will generate links using that empty string. We should treat these cases as the same as not passing in a releases list.

I noticed that at least in the sidebar is some invalid HTML:

<ul class="bs-docs-sidenav bs-sidenav nav" role="complementary">
  <ul class="toctree nav nav-list">
    <ul class="current">

The <ul> tags are not allowed to be directly nested. There might be further instances of invalid HTML in the theme. Reasons why it might be worth to care about this.

The links to various appliedbrainresearch.com subpages need to be updated to the new locations after the reorganization there.

To avoid issues like #28, we should pin the Sphinx version and write a release checklist that includes upgrading the Sphinx version and trying a few common tasks to ensure the Sphinx update doesn't break anything.