jupyter-book

jupyter-book copied to clipboard

It might be helpful to include something like this in the toc file. I don't see a way to do that now but I might be wrong.

hmmm - I am not sure how this usually works in Sphinx, but it seems reasonable to allow people to reset equation numbers. I think maybe it's controllable with the {math} directive?

@najuzilu is this one still an issue for you? I'm not sure it's something that we could fix at the CLI level, but correct me if I'm wrong

I think the solution would be to use :math_numfig: with :numfig_secnum_depth:. This is generally added at the toctree directive in Sphinx. I'm guessing we don't currently support this at the CLI level, correct?

nope, the CLI doesn't trigger behavior like that, but users could configure it in their directives or in their configuration files as needed

I'm not sure exactly what's being requested but what would be really perfect here is if the equation numbers matched across the PDF and HTML.

@boazbk has implemented this (at least for theorems) in https://github.com/boazbk/tcs.

Either way, my vote is that eq numbers are universal rather than local, so "equation 3.2" always refers to exactly one equation in the book.

I think "equation numbers are universal" should definitely be the default as well

The way I implement all references in my book is that I run latex first, and then have a python script that scans the aux file to get the numbers that correspond to all references. See https://github.com/boazbk/panbook/blob/master/auxtoyaml.py and getlabel in https://github.com/boazbk/panbook/blob/master/book-filter.py

@jstac Our lectures' eq counter - see scalar_dynam and finite_markov- is reset to 1 for every lecture. This seems to be the default behavior. Currently, quantecon-example does not reflect this.

@choldgraf I'll see if this can be done at the directive level and report back.

Something else to consider is adding numfig_format. It would be helpful to format eq/table/fig labels at the toc level. What do others think?

@jstac this is similar to ExecutableBookProject/cli#92 but set at the toc level instead of manually updating the label.

Thanks @najuzilu. I think there's agreement now that equation numbers should not reset at each lecture, and should be unique through the document. Ideally, they would take the LaTeX form (3.2) for second equation of third lecture, etc.

Even better if they can match the PDF numbers, although that might be a long run target.

It would be helpful to format eq/table/fig labels at the toc level.

I'm not sure what this means. Can you please give an example?

@jstac thanks for clarifying.

I'm not sure what this means. Can you please give an example?

The numfig_format is used as a caption prefix for referencing figures/tables etc.. The default behavior is "Fig. 1 <caption>". It allows the user to reset the prefix caption to something else, for example "Figure x: <caption>", but this is done at the toc level for all figures.

When you say toc level, do you mean _config.yml? That's the bit I'm confused about

Yes, apologies for the confusion. It would have to be under _config.yml

ah - in that case I agree, I think it's a good idea :-)

here's the config section where we'd control this, so the question is just where in the _config.yml file we want that configuration to go: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig_format

also relevant is that it seems like here they explain how equation numbering works: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig_secnum_depth

I have started using JB and encounter a connected issue.

My TOC looks like:

• file: file1 numbered: true

• part: Part1 chapters:

  • file: file2
  • file: file3

• part: Part2 chapters:

  • file: file4
  • file: file5

Imagine I have 3 or 4 equations per files starting in file2. The equation numbering in each file is then:

Part1 file2: 1.1, 1.2, 1.3, 1.4 file3: 2.1, 2.2, 2.3

Part2 file4: 1.5, 1.6, 1.7 file5: 2.4, 2.5, 2.6

In other words, the equation numbers run consecutive in chapters running in different parts. All 1st chapters are connected and so on.

I did not get from the above discussion if it was possible to control this behaviour. A workaround would be to never reset the counter. Is there an option for that?

EDIT: I understood how to control the numbering just a few minutes after posting. By adding this to the config file,

sphinx:
  config:
    numfig_secnum_depth: 0

the counter is never reset. Great !

@bknaepen re: the part/chapter structure section numbering can be adjusted by using this extension:

https://github.com/executablebooks/sphinx-multitoc-numbering

and adding it to extra_extensions in the _config.yml after installing it via pip. It will probably make its way in to jupyter-book as a dependency soon and be the default behaviour for part/chapter structures to support continuous numbering across parts and chapters.

@mmcky That sounds really nice. I'll give it a go. Thanks !