How to make this example better.

[jstac]

The current plan is for this mini project to be a starting point for users of the CLI, who are encouraged to download, build and view it. The project will feature in the docs as an example that helps people get started quickly.

Discussion is here: https://github.com/ExecutableBookProject/meta/issues/46

Here's how they look now.

We already have glue, citations, numbered eqs. What else do we want to add before we go ahead? I would like to see numbered figs with references to them.

What do others want? CC @choldgraf @najuzilu @mmcky

(There are also some small bugs like the TOC appearing twice in the left hand menu and figures not being properly centered.)

[choldgraf]

I think that the reason that the TOC is showing up twice is because there's a toctree on the pages...we don't need to use toctrees at all in Jupyter Book since we use _toc.yml.

For figures - do we want all figures / images / tables / etc that aren't part of code cells to be centered by default?

[jstac]

Thanks @choldgraf . So I originally added the TOC (now removed in order to get rid of the bug) because of one thing I'm not so keen about the existing theme:

If you look at the top level page now, the TOC is just in the side bar, as intended. But it's faded, which makes it less obvious as the entry point.

As a reader, I would rather have a dedicated TOC page, like this, so I can get a nice clear overview of the contents.

What do you think about this? What do others think CC @mmcky @najuzilu @gregcaporaso ?

If you prefer the existing style, @choldgraf , perhaps the best way forward for the QuantEcon team is to start putting together an alternative theme. (CC @drdrij). So it would be good to know.

[jstac]

Regarding positioning of figures included via a figure directive, this page is a good example.

Having them centered by default seems more standard to me. And if I look at the caption of Fig 1, a more standard layout would be to have that text centered under the figure.

The other issue regarding those figures is that there's no white space under them. (For example, search for the text "What you see here is called the Jupyter dashboard.") Visually it would be nicer if there was some padding. And it would distinguish text from captions.

I mentioned this to @najuzilu and suggested she open a separate issue if she agrees but I'm not sure if she's done so?

[choldgraf]

I think it's a good idea to treat figures as differently from regular images. Can you give me an image of the optimal HTML-based figure style that you'd like to see?

[choldgraf]

(if that's something that @najuzilu would like to play around with, I'm happy to review PRs in the CSS...I think the fix would be in the sphinx-book-theme SCSS file)

[jstac]

Can you give me an image of the optimal HTML-based figure style that you'd like to see?

The first figure on this page looks good, IMO. Centered, with a bit of padding around it.

https://python-programming.quantecon.org/about_py.html

There's no captions on figures but if there was one I would prefer it to be center-aligned.

[choldgraf]

looks good to me too - maybe with an italicized caption as well? And maybe with the Fig. 1 in bold?

[najuzilu]

@jstac I'm working on fixing the css discrepancies. I agree with @choldgraf that these edits should be made in sphinx-book-theme. As discussed here, I'm also adding documentation on how to override css.

@jstac I'd like to add/test out the sidebar functionality. I like the idea of writing in the margins. What do you think?

[choldgraf]

@najuzilu I just had a moment and made some CSS updates over here: https://github.com/ExecutableBookProject/sphinx-book-theme/pull/51

Wanna take a look and let me know what you think?

[choldgraf]

also - any interest in writing up a short section on using figures in the CLI docs? What do folks think about making this page include figures as well and adding the figures section there

[najuzilu]

I already have a branch on which I'm working on figure docs for the CLI, so I can add the changes you made there and make a PR. I'm not sure I understand the second question. What kind of figures did you have in mind?

[choldgraf]

I just mean adding in documentation about how to create figures for users that may not be familiar (also, an example of the figure sidebar options, which are non-standard in Sphinx)

[najuzilu]

There's some basic figure information under Extended markdown with MyST Markdown. This will stay intact correct?

[choldgraf]

Ah good catch maybe we should just add figure information there then

[choldgraf]

I think the longer term question there is whether the content will get big enough that "extended markdown" should be it's own separate collection of pages...

[mmcky]

I think that the reason that the TOC is showing up twice is because there's a toctree on the pages...we don't need to use toctrees at all in Jupyter Book since we use _toc.yml.

I agree with @jstac on this. I think it is useful to have an overall view of the toc as an option. Perhaps we could introduce breadcrumbs and have a toc page at the root of that listing? I think inevitably we will need some theme variants to meet everyone's needs too (with a default theme such as the current one).

A few other comments.

The right hand with-in page listing doesn't seem to show any subheadings on the individual pages. Is this intentional?

re: theme on safari there seems to be a lot of whitespace and a pretty narrow content column. I see you can hide the left hand bar but that just seems to move the content over and remove the context. It might be great if the content got more space when you tuck the other elements away.