search

jupyter-book / jupyter-book

Create beautiful, publication-quality books and documents from computational content.
http://jupyterbook.org
BSD 3-Clause "New" or "Revised" License
3.8k stars 653 forks source link

CLI toc Generation - Sort Order #1276

Open psychemedia opened 3 years ago

psychemedia commented 3 years ago

PR https://github.com/executablebooks/jupyter-book/pull/1210 fixed alphanumeric sorting of files in table of contents (toc) generation, but are other sort orders possible and should there be a means of controlling them?

If there are multiple directories to be indexed, passing a comma separated list of directory names might be one way for a user to generate a table of contents with directories/sections ordered in a specific way. A useful side effect of such a facility would also allow a user to specify a subdirectories in a content directory in an inclusive way, eg jupyter-book toc --include first,middle,last content in:

content/
  excludethis
  first
  last
  middle
  notthis
  orthat

Identifying requirements for how folk want to work with toc generation also relates to https://github.com/executablebooks/jupyter-book/issues/1272 .

chrisjsewell commented 3 years ago

note in #1293 the sorting is now by natural order (see also https://github.com/executablebooks/sphinx-external-toc/pull/14)

If there are multiple directories to be indexed, passing a comma separated list of directory names might be one way

I don't see this is ideal, since it assumes a single nesting depth, and would require lots of extra code complexity to achieve. It also feels that if you are going to start having to write all this extra text/logic into the command, why not just generate the toc.yml then modify the order by hand?