Documentation renders option types as part of the name?

[mgedmin]

Look here:

https://jupyter-notebook.readthedocs.io/en/stable/config.html#options

Is the option named NotebookApp.use_redirect_fileBool, or is Bool an option type, which is for some reason mistakenly rendered without any separation from the option name?

[jameslamb]

I just came here to report the same thing. In the example above, the config option is NotebookApp.use_redirect_file, and it has type Bool. But it's hard to see that from scanning the page.

I'd like to work on this. I've done some investigation already, and I think I see where to start.

The docs at that page are generated by a call to notebook.NotebookApp.document_config_options() in docs/autogen_config.py

notebook/docs/autogen_config.py

Line 45 in a5ace13

f.write(NotebookApp().document_config_options())

.

notebook.NotebookApp gets that method from the parent class jupyter_core.JupyterApp

notebook/notebook/notebookapp.py

Line 677 in 2cfff07

class NotebookApp(JupyterApp):

Which gets that method from its parent, traitlets.config.Application

https://github.com/jupyter/jupyter_core/blob/e69a436529838dce8b41e6d4508f94930c87b559/jupyter_core/application.py#L47

https://github.com/ipython/traitlets/blob/2bb2597224ca5ae485761781b11c06141770f110/traitlets/config/application.py#L543

So I think that the right place to fix this is over in in traitlets (https://github.com/ipython/traitlets).

[jameslamb]

Ok I spent a little time on this tonight, following the instructions at https://github.com/jupyter/notebook/blob/master/CONTRIBUTING.rst#building-the-documentation to build the documentation, and couldn't figure it out.

When I build the docs locally following that guide, I get a different theme for this page.

https://jupyter-notebook.readthedocs.io/en/stable/config.html#options

local docs

So I'm not really sure how to proceed. Hopefully the notes I've provided above will help someone else pick up this issue in the future.

[mgedmin]

IIRC ReadTheDocs have a custom Sphinx theme that they use by default.

The HTML on ReadTheDocs looks like

<dt>Application.show_config<span class="classifier">Bool</span></dt>

The Sphinx source of the page is ... missing? I get a 404 error if I press the edit on GitHub button at the top of the ReadTheDocs page. I get the feeling it's generated dynamically. (Which was clearly explained in an earlier comment that I didn't bother to re-read today, mea culpa)

Docutils's own docutils/docutils/writers/html5_polyglot/minimal.css has this styling for span.classifier:

/* Definition Lists and Derivatives */
dt .classifier { font-style: italic }
dt .classifier:before {
  font-style: normal;
  margin: 0.5em;
  content: ":";
}

It looks like the ReadTheDocs's sphinx_rtd_theme's stylesheet is missing correct styling for .classifier, and maybe this issue should be forwarded to https://github.com/readthedocs/sphinx_rtd_theme/issues?

In fact isn't readthedocs/sphinx_rtd_theme#746 exactly this issue? But it was closed last year?